Payment Gateway
  • 06 May 2024
  • 6 Minutes to read
  • Dark

Payment Gateway

  • Dark

Article summary

The following fields were added to the Payment Gateway object.
  • Field Name: TouchNet uPay Site ID
    • API Name: bt_stripe__TouchNet_uPay_Site_ID__c
    • Data Type: Text(15)
  • Field Name: TouchNet uPay Site URL
    • API Name: bt_stripe__TouchNet_uPay_Site_URL__c
    • Text(255)

In Blackthorn Payments, a Payment Gateway record is synonymous with a gateway account (i.e. Stripe, etc.) account. Each Payment Gateway record you create connects your Salesforce org to one gateway account, in either test or live mode. To have your gateway account in both test and live mode, create two Payment Gateway records. There is no limit on the number of Payment Gateway accounts you can connect to your org.

Note on Payment Gateway Records

Do not change your Payment Gateway record from test mode to live mode or vice versa by clicking Connect to Gateway or checking/unchecking the Test Mode checkbox. Instead, create a new record for the other mode you wish to enable.

Supported Payment Gateway Providers

Blackthorn supports several Payment Gateway providers. The primary Payment Gateway providers are Stripe,, and Spreedly. Blackthorn also supports the providers below via one of the primary providers.


* Apple Pay
* Google Pay
* Alipay
* Bacs Direct Debit
* Bancontact
* Giropay
* Plaid (must be set up in Stripe)
* SEPA Direct Debit


  • via Spreedly - fully tested


The following Spreedly processors are used by Blackthorn customers.

  • Braintree
  • Cardconnect
  • Elavon
  • eWAY
  • Fat Zebra
  • Litle
  • Orbital
  • Payflow Pro
  • Paypal
  • Sage

What is the fee per transaction when using PayPal as a payment gateway?
The fee per transaction when using PayPal as a payment gateway is 3.49% + a flat fee depending on the country. The flat fee for the USA is 0.49 USD (standard rate).

Events and Catalog Checkout

Blackthorn also supports two Payment Gateway providers that only work with Events Checkout and Catalog Checkout.

  • TouchNet
  • CashNet

First Payment Gateway Record

Your first Payment Gateway record, named "primary" was created automatically during the Setup Wizard. Follow the steps below to locate it.

  1. Open the Blackthorn | Payments (Admin) app.
  2. Click the Payment Gateways tab.
  3. Select All from the list of List Views.
  4. Click on the record named "primary".

If you connected to your gateway account in test mode, the Test Mode field will be checked.

The primary Payment Gateway record includes the following.

  • The Default field is checked.
    Objects with a Payment Gateway lookup field (such as a Transaction and Payment Method) will default to the Payment Gateway record with the Default field checked if the Payment Gateway field is blank.

  • The Gateway Information section provides all the connection details.
    If these fields are blank, the data in Salesforce will not process in the gateway. Do not copy your Stripe API keys and insert them here as these keys are different than your Stripe keys (they are OAuth keys). You can only get them by clicking the Connect to Gateway button.

H_01_07_first payment gateway record

Create Payment Gateway Records (for Stripe)

Create a Payment Gateway for Stripe

Each Stripe account mode (test and live) needs its own Payment Gateway record. This is to ensure that your data is separated from "Live" and "Test".

If you connected to your account in Test Mode during setup, create a new Stripe Payment Gateway record for live mode.

  1. Open the Blackthorn | Payments (Admin) app.
  2. Click the Payment Gateways tab.
  3. Click New.
  4. Populate the following fields:
    • Payment Gateway Name (required)
    • Provider (required)
    • Webhook Label = Name for the webhook URL. This is needed to configure webhooks.
    • Default= Check this field if you want this as your default Payment Gateway.
      If you have multiple Stripe Payment Gateways, you can change which one is the default.
    • Test Mode = Check this field if you are connecting to your Stripe account in test mode.
  5. Click Save.
  6. Click Connect to Gateway.
  7. Enter your Stripe credentials.

Once you sign in, all fields under the "Gateway Information" section in the Payment Gateway record will be filled out.

Syncing Stripe Data to Salesforce

There won't be data in the Related Lists section. Connecting to your Stripe Account does not automatically sync existing data to Salesforce. If you have data in your Stripe Account that needs to be moved to Salesforce, review the Historical Sync documentation.

Available and Pending Balances

The Payment Gateway object allows you to track an compare your available and pending balances for both Salesforce and Stripe.


Stripe Balance Available and Stripe Balance Pending
These fields are updated via the Stripe's Balance.Available or Account.Updated Webhook Events.

Stripe Balance Last Updated
This date and time field is updated when the balances are updated, giving you an insight as to when the two balances were last updated.

Held in Reserve
This field shows the funds held in reserve due to negative balances on Connected Accounts. Stripe automatically updates this field via a webhook.


Calculate Salesforce Balances From
This field is for calculating historical transactions that were processed through Stripe before the balance fields were packaged.

Salesforce Balance Available and Salesforce Balance Pending
These fields are automatically calculated based on the related Transactions.

  • If the related Transaction's Balance Status = "Available", then the Retained Net Amount is rolled up to the Salesforce Balance Available.
  • If the Transaction's Balance Status is "Pending" then the Retained Net Amount is rolled up to the Salesforce Balance Pending.

Stripe Balance Last Updated
This date and time field that is updated when the balances are updated.

Balance(s) Incorrect
When this field is checked, it means the Stripe Balance Available and Salesforce Balance Available fields, and the Stripe Balance Pending and Salesforce Balance Pending fields do not match. Often, they don't match because the timing of the Stripe webhook and the Salesforce batch process doesn't line up.

Update Balance Button
Clicking this button forces a daily apex job to update the Salesforce and Stripe available and pending balances immediately.


If you have a high Transaction volume, don't click the Update Balance button. You will run into a query limit error.

H_01_07_available pending balances_salesforce

Scheduled Apex Job

The Blackthorn | Payments Balance Update scheduled job runs daily. It updates the Stripe Balance Available, Stripe Balance Pending, Salesforce Balance Available, and Salesforce Balance Pending fields on the Payment Gateway record(s).

  1. Navigate to Setup.
  2. In the Quick Find box, enter and click "Scheduled Jobs."

H_01_07_scheduled apex job

Block Amex Payment Methods

Some providers, like Stripe, charge higher fees to use an American Express payment method. To help customers mitigate the extra fees, we added the Block Amex Transactions In Rest API field to the Payment Gateway object to block Transactions from the REST API that attempt to charge a payment with an American Express card. This field can be used with the following.

  • PayLink
  • DocumentLink
  • REST API requests (custom front-end code)

Remember to add this field to your Payment Gateway page layout if you want to use it.

Here's what a customer may see if the Block Amex Transactions In Rest API checkbox = "True" (checked).

H_01_07_block amex pm

Payment Gateway Owner - Known Limitation

If you have configured a Sharing Rule for the Payment Gateway object, there is a known limitation in Salesforce. If the Payment Gateway Owner = "Automated Process User", Sharing Rules won't be applied. The work around is to update the Owner field to reflect another user in your org such as the System Administrator. Read more about this here.

Delete a Payment Gateway

Before you can delete a Payment Gateway, you must first delete any related Payment Gateway Customers and Payment Methods from the Payment Gateway.

  1. Open the Payment Gateway record and review the Payment Gateway Customer and Payment Method Related Lists.
    Delete a Payment Gateway 1
  2. Open a Payment Gateway Customer record.
  3. In the navigation menu, click Remove From Gateway.
    Delete a Payment Gateway 2
  4. The Deleted From Payment Gateway field will be checked.
    Delete a Payment Gateway 3
  5. Repeat the process for any other related Payment Gateway Customer records.
  6. Open a Payment Method record.
  7. Click Remove From Gateway.
    Delete a Payment Gateway 4
  8. Go back to the Payment Gateway record.
  9. In the record’s navigation, click Delete.
    Delete a Payment Gateway 5

The Payment Gateway record is now deleted.


If you have received an error with your Payment Gateway or have a question, please view our Troubleshooting page.