Install & Setup
  • 09 Jul 2024
  • 4 Minutes to read
  • Dark

Install & Setup

  • Dark

Article summary

Package Install

  1. Install the latest version of Blackthorn Payments and complete the setup wizard.
  2. Install the Blackthorn Mobile Payments package in a sandbox or production and assign licenses to all users that need access.
  3. Install our iOS app.

Add Mobile Pay Action to Transaction Page Layout

The Mobile Pay action can be added to the Transaction page layout to link the Salesforce mobile app to the Blackthorn Mobile Payments app. This allows Salesforce mobile app users to take a mobile payment.

Follow the steps below to add the Mobile Pay action to the Transaction page layout.

  1. In Salesforce, click the Gear icon to go to Setup.
  2. Click the Object Manager tab.
  3. In the Quick Find box, search for and click the Transaction object.
  4. Click the Page Layouts tab.
  5. Click the Charge Transaction Layout.
  6. Click the Mobile & Lightning Actions tab.
  7. Drag and drop the Mobile Pay action in the Salesforce Mobile and Lightning Experience Actions section.
  8. Click Save.

Select a Payment Gateway

If you are using Stripe, you must confirm that a location is set for the Payment Gateway in Stripe before using the Mobile Payments app.

The user can select a Payment Gateway when creating a Transaction either in Salesforce or in the Mobile Payments app. If there are multiple Payment Gateway records, the app will default to the default Payment Gateway.

If the user creates the Transaction from the Mobile Payments app, they can select a Payment Gateway on the Home page. Initially, the default Payment Gateway will be selected. If a user selects a different Payment Gateway, the app will remember the new selection the next time a new Transaction is created.

Enable Send Receipt Email in Salesforce

After a mobile transaction is complete, Salesforce can send a receipt via email to the customer if the Receipt Email field is populated AND the Transaction Status = “Completed”.

Follow the steps below to enable this feature.

  1. In Salesforce, go to Setup > Workflow Rules.
  2. Click Activate next to "Send Blackthorn | Payments Receipt (Text)".

Set Up Stripe Locations

Before using your Stripe account, confirm that Locations have been set up. All card readers require an assigned Location. Use the following steps to set up Locations in your Stripe Dashboard if they aren’t already set up.

  1. Log into your Stripe Dashboard.
  2. Click Payments.
  3. Click Readers.
  4. Click Locations.
  5. On the Locations page, click New.
  6. Enter the name and address details for each physical location.
  7. Click Save.
  8. Once you’ve created each Location, click New in the Location’s “Reader” section to register each card reader to a Location.

Card Reader Firmware Updates


Stripe users need to add locations to their Stripe dashboard before upgrading their iOS mobile devices to the latest version. If the locations are not added first, users will be unable to connect to a Stripe card reader.

We've added the ability to update your card reader firmware inside the Mobile Payments app.

  1. Navigate to the Reader screen.
  2. Connect your reader.
  3. Notice that while connecting the reader, we are checking for firmware updates.
  4. If your reader has a firmware update available, a link to install the update will appear.
  5. Follow the on-screen prompts to install the update.
Connecting a Stripe Card Reader

When connecting a Stripe card reader, a modal screen will appear on the Mobile Payments app to ask for Bluetooth permissions for the following new permissions in Android 12 or higher. It may take up to two to three minutes for the card reader to appear on the screen.

  • BLUETOOTH_CONNECT: required to connect to paired Bluetooth devices.
  • BLUETOOTH_SCAN: required to scan and pair nearby Bluetooth devices.
  • BLUETOOTH_ADVERTISE: required to advertise to nearby Bluetooth devices.

Save Card Details with the Stripe Terminal

There are two options for collecting reusable card details with Stripe Terminal. Please click one of the options below for specific instructions from Stripe.

Virtual Terminal Custom Setting

Before using Spreedly with Cybersource to accept payments, the Virtual Terminal custom setting Show Address must be enabled. This ensures that the address fields (Street, City, State, and Country/Region) will be visible on the Payment Method creation page in the Virtual Terminal.


Skip Receipt Screen Custom Setting

iOS Mobile Payments app users can now use the Blackthorn Payments | Mobile Settings custom setting Skip Receipt Screen to determine if the last screen will show the option to send a receipt.

  • If Skip Receipt Screen = “True” (checked), the last screen won’t show the option to send a receipt.
  • If Skip Receipt Screen = “False” (unchecked), the last screen will show the option to send the receipt.

To update the setting, follow the steps below.

  1. Click the Gear icon.
  2. Click Setup.
  3. In the Quick Find box, enter and click “Custom Settings.”
  4. Click Manage next to Blackthorn Payments | Mobile Settings.
  5. Click New.
  6. Check the Skip Receipt Screen checkbox.
  7. Click Save.


If you need to determine which software version was used for a Transaction, add the Mobile App Version field to your Transaction object. The Mobile App Version will automatically populate with the application platform name (iOS or Android) and the version number.

If you have any questions about the setup process, please contact Blackthorn Support. We're happy to help!