Knowledge Base

This integration option keeps the user in your application with your pages for a consistent user experience.

To start, there are a few configuration values that must be stored in the Integrating System. The configuration values are broken into two categories – values that must be stored at the system level and are shared across all clients and values that are specific to each client.

• API Url – The Url for the API. The default page loads the Swagger UI for full documentation of the API.
• API Key – The key for the API. This should never be shared with outside entities.
• API Secret – The secret for the API. This should never be shared with outside entities.
• API Public Key – The Public Key can be shared with outside entities since it can only be used to create payment tokens while the Key and Secret can be used to run any operation on the API.
• Impersonation Key (optional) – When combined with the Key and Secret or Public Key, the Impersonation Key, gives authorization to the Integrating System to run transactions on behalf of the Client. If the Integrating System is for a single entity and not on behalf of a number of different clients, then any reference to an Impersonation Key in this documentation can be ignored and this can be left null.

Step 1: Create the Token Page Session Id
Authentication Required for this step: API Key, API Secret (and Impersonation Key if applicable)

The first step is to create a “token page session Id” which will allow you to redirect the user to a hosted page on our servers to collect the payment information. Pass in any custom attributes to attach to the transacation, along with a success Url which your payer will be forwarded to once a payment method is successfully saved through the hosted page.

The session Id returned by the API is valid for 30 minutes.
Sample code for creating the token page session Id can be found here.

 

Step 2: Forward your Payer to the Hosted Page
Authentication Required for this step: None

Your application forwards the user to the hosted page with the session Id in the query string (tokens?sessionId={sessionId}). Once a payment method is saved, the user will be forwarded back to the success Url specified in Step 1 along with the token Id in the query string (?tokenId={id}).

 

Step 3: Store the Token (optional)
Since the token is reusable, the token can be stored locally so the user can reuse the payment method on a subsequent visit without having to enter in the information.

 

Step 4: Show the Fees (optional)
Authentication Required for this step: API Key, API Secret (and Impersonation Key if applicable)

The payer should be shown the fee (aka “Payer Fee”) of the transaction if they are covering the fee. The POST /transactionFees endpoint will respond with a calculated payer fee for ACH and a calculated payer fee for credit card which can be shown to the user so they can decide on their preferred payment method.

The API documentation can be found here.

 

Step 5: Execute the Payment Transaction
Authentication Required for this step: API Key, API Secret (and Impersonation Key if applicable)

Using the API and the token Id from the query string, execute a GET operation against the API to obtain the token details including any custom attributes passed in during Step 1. The payer fee should be specified in the PayerFee field of the request and the PayerFee should also be included in the Amount field. For example, if the net amount due is $100 and the PayerFee is $3, then the Amount should be 103 and the PayerFee should be 3.

The payload below shows the only fields that are recommended for creating a payment transaction.

{
"payer": "John Smith",
"amount": 100,
"payerFee": 3,
"attributeValues": {},
"comments": "These are optional comments",
"emailAddress": "jsmith@example.com",
"tokenId": "[Token Id goes here without brackets]",
"sendReceipt": true,
"ipAddress": "127.0.0.1 [This is optional but it is recommended to send the user’s IP address.]"
}


The response contains the transaction Id in the “Location” header attribute if successful. A user-friendly error message will be in the body of the response if the transaction was unsuccessful.

The API documentation can be found here.