• 09 Apr 2024
  • 8 Minutes to read
  • Dark

  • Dark

Article summary

If you were an customer before coming to Blackthorn | Payments, you may want to sync your customers and Payment Methods from into Salesforce. Please refer the documentation below for instructions to migrate the historic customers and Payment Methods into Salesforce.


With, we support over 20 processors. The list of supported processors is here.

When setting up, you can either use as a processor or use any number of their supported processors. The pricing will vary.


The Payment Gateway is currently supported with PayLink, DocumentLink, and the Events checkout.


If you do not have an account and need one, please fill out this form. If you have a contract with one of the supported 20+ processors and want to use as your Payment Gateway, you'll need an account. Use these account credentials to connect your Payment Gateway following the setup doc below.

Customer Information Manager

If you've had an account for a while (pre 2018) you'll want to ensure that you've enabled the Customer Information Manager. This will ensure you don't run into unexpected errors later. From your account goto Tools > Customer Information Manager > Click "Sign up for Customer Information Manager (CIM) Now". Check out this article for more information and screenshots.

Setup Permission Requirements

The user who connects the payment gateway to must have the following permissions checked on their Account Owner Profile.

  • Permissions Key
    • Irrevocable permission
  • Transaction Processing Permissions
    • Create charge transactions
    • Create refund transactions
    • Update unsettled transactions
    • Manage ARB subscriptions
    • Manage CIM profiles
  • Settings Permissions
    • Edit transaction format settings
    • Update transaction security settings
    • Edit basic fraud settings
    • Edit AFDS settings
    • Manage mobile devices
  • Account Level Permissions
    • Update business information
    • Manage account services
    • View account finances
    • View/download eCheck.Net NOC reports
  • User Management Permissions
    • Manage account users Required Permissions

Create a Payment Gateway

Multiple Currencies

If you are a customer that needs to support multiple currencies through your Payment Gateway you will need to create an gateway for each currency. This is a limitation for

We do have a validation you can enable to make sure your Transaction record currencies match your Payment Gateway currencies. Check it out here.

To begin, you will need to create a Payment Gateway record to connect to your account. It can be done via the Payment Setup Wizard or the Payment Gateway tab.

Using the Blackthorn | Payment Setup Wizard

  1. Navigate to Blackthorn | Payments (Admin) app and click the Blackthorn | Payments Admin tab.
  2. Set Provider = "".
  3. Check "Test" if you want to connect to your sandbox.
    If you don't have a sandbox account yet, create a sandbox for testing.
  4. Click Connect to Gateway.
  5. Complete the Payments Setup Wizard flow.

H_02_01_create payment gateway 1

Once the Setup Wizard is completed, you'll notice that the Gateway User EmailGateway Public Key and Payment Gateway Account Country fields are auto-populated. This means that the Payment Gateway is successfully connected.

H_02_01_create payment gateway 2

Using the App Launcher

  1. Navigate to the App Launcher and select Blackthorn | Payments (Admin) app.
  2. Navigate to the Payment Gateways tab and click New.
  3. Define the Payment Gateway Name.
  4. Set Provider = "".
  5. Check "Test" if you want to connect to your sandbox.If you don't have a sandbox account yet, create a sandbox for testing.
  6. Provide a Webhook Label, if webhooks are implemented (Optional).
  7. Provide a valid currency code in Default Currency, a blank Default Currency is considered "USD".
  8. Click Save.

H_02_01_create payment gateway 3

  1. Once the record is saved, click Connect to Gateway.

H_02_01_create payment gateway 4

The Gateway User Email, Gateway Public Key and Payment Gateway Account Country will be auto-populated once the gateway is successfully connected.

H_02_01_create payment gateway 5

Define the Gateway User ID

Now that you are connected to your Payment Gateway, you need to manually copy the “API Login ID” from your account and paste it into the Payment Gateway Gateway User ID field.

  1. Log into your account.
  2. Click Account and then API Credentials and Keys.H_02_01_define gateway user id 1
  3.  Copy the “API Login ID”.H_02_01_define gateway user id 2
  4.  Enter the “API Login ID” in the Gateway User ID field.H_02_01_define gateway user id 3
  5.  Click Save.

Add a Payment Method

Follow the instructions below to set up Credit Card and ACH Payment Methods with

Create a Transaction

  1. Create a new Transaction record (Charge).
  2. Set the Payment Method lookup field to an related record.
  3. Enter an Amount.
  4. Enter a Description (Optional).
  5. Set the Invoice Number (Optional) - You will need to add this field to the page layout.
  6. Click Save.
  7. Click Capture or Authorize.

Refer to the Charge a Transaction guide for additional information.

Refund a Transaction

Refunds and Payment Gateways
Partial and full refunds can only be processed via once the original Transaction is fully settled.

Click Refund to refund a captured Transaction or to release an authorized Transaction.

Duplicate Transactions

To prevent incorrect duplicate Transactions when using, a new custom setting labeled “Duplicate window” was added to Blackthorn Pay - Trigger Settings. The new custom setting includes the following functionality.

  • The user is UNABLE to capture the duplicate Transaction when
    • the Transaction is within the time mentioned in the Duplicate window custom setting
    • the Duplicate window = “NULL” in Custom Settings
  • The user is ABLE to capture the duplicate Transaction when
    • the time is after the time set in the Duplicate window custom setting
    • running the Batch Job

Transaction Errors

An error code and message are provided in the Error Message and Error Code fields when a Transaction fails.

Review the response codes to find specific details about the Error Code (Response Codes).

To generate a failed Transaction for testing, visit Testing Guide.


Webhooks provide a mechanism where a server-side application (in this case can notify a client-side application (in this case Payments) when a new event (like customer create, update, delete, charge capture, charge failed, etc) has occurred on the server.

Webhooks automatically send specified data to a destination (endpoint) from database events.

Follow our instruction guide here for setting up webhooks in

Create a Customer in the Portal

If you have created a Customer Profile in, webhooks can update Salesforce and add the new Payment Gateway Customer record and Payment Method record.


  • Payment Profile information will used to populate the Payment Method record.
  • Customer Profile in does not contain many fields. In order to populate the Payment Gateway Customer record, fields from the Payment Profile may be used.
    • Example: Payment Profile Name = Payment Gateway Customer Name.

Visa Checkout (Optional)

Get the Visa Key from

  1. Login in your account.
  2. Click Account tab > Digital Payment Solutions.
  3. Click Signup next to "Visa Checkout".
  4. Capture the "Visa Key" from the Visa Checkout API Key section.

Create a Salesforce Site (if not yet created)

  1. Register with a site domain in Salesforce. Setup > Search for Sites > Sites > Register with a unique Domain > New.
  2. Fill in the required information.
  3. Set any page to Active Site Home Page = "True".
  4. Click Save.
  5. Capture the URL and Path. Ex.

The client-side HTML will call start () function to init (payload). You have to use the "Visa Key" in the HTML. The same value will be stored in the Gateway Public Key field on the Payment Gateway.

Migrate Payment Methods and Customers

If you were an customer before coming to Blackthorn Payments, you may want to sync your customers (Customer Profile), Payment Methods (Payment Profiles), and Transactions from into Salesforce.

This guide will help you understand our object model so you can easily sync the information using the Data Loader tool.

  1. Create a Payment Gateway in Salesforce and connect to your account.
  2. Export customers and cards information from gateway into an excel document. Please convert to CSV type file.
  3. We have two objects in Salesforce - Payment Gateway Customers and Payment Methods where this information will be mapped. Prepare an excel spreadsheet with this customer information mapping to respective fields on the Payment Gateway Customer/Payment Method.
  4. In Salesforce, go to Custom Settings > Blackthorn | Payment Triggers > Edit > Disable all triggers.
  5. Contact Blackthorn Support to disable CVV and Postal Code checks. (If you have information about the postal code, we can skip disabling this for you.)
  6. Download the CSV file and import into the Payment Gateway Customer in Salesforce using the Data Loader.
  7. Export the Payment Gateway Customer list from Salesforce and locate the record ID. Map the record ID in your Excel spreadsheet to Payment Gateway Customer lookup field on the Payment Method before importing.
  8. Import the Payment Methods into Salesforce.
  9. Visit Custom Settings to “Enable all triggers”.

Customer Field Map

Salesforce Field Label
Payment Gateway CustomerPayment Profile
NameFirst Name + Last Name
Customer IDCustomer Profile ID
Billing City (Optional)City
Postal Code(optional)ZipPostal Code
Billing Street 1 (Optional)Address
Billing State (Optional)StateProvince
Billing CountryCountry

Payment Field Map

Salesforce Field Label
Payment MethodPayment Profile
Holder’s NameFirst Name + Last Name
Email (Optional)Email
Card IDPayment Profile ID
Customer IDCustomer Profile ID
Record Type(Card/ACH)Payment Type (CreditCard/Bank Account)
State (Optional)StateProvince
Country (Optional)Country
Last 4 DigitsCardNumber (last 4 digits)
Payment Gateway (lookup)Hardcode the PG id
Payment Gateway Customer(lookup)Fetch id from SF
Payment Method StatusValid

Alternative Migrating Method

To link the Contacts and/or Accounts to the Payment Gateway Customer or Payment Method records, complete the following steps.

  • Create a report in Salesforce for Contacts with the First Name, Last Name, Email, and Record ID fields.
  • Export them to a CSV file.
  • Create and export a report of all Payment Gateway Customer records with Name, Email and Record ID fields.
  • In Sheet B, create a new column "Contact" and add the formula to match the contacts to the Payment Gateway Customer via email.
  • Download to CSV then import them back into Salesforce with size 1.
  • Once the Contact lookup is set on the Payment Gateway Customer, it will auto-update the related Account as well as update all associated Payment Methods with the set Contact and Account.
Using a Process Builder

If you want a Contact record created, you can create a Process Builder to create a Salesforce Contact when the Customer record is created in Salesforce.

This sync process is only to migrate your records from that moment backwards. Syncing with Salesforce going forward can be done through webhooks, but you should not be originating records outside of Salesforce.

Testing data

Find the testing information for here.


If you have received an error with or have a question, please view our Troubleshooting page. If you still have questions, please contact Blackthorn Support. We're happy to help!