Detailed Client-Side Integration

An in-depth outline of the client side integration process

This document walks through the “client side” integration mentioned at epaypolicy.com/integration While the integration page on the website introduces the concept, this document goes further in depth on each individual step of integration.

Terms

The following terms are used throughout this document.

Integrating System” is used to refer to the system that controls the user experience integrates back into ePayPolicy.

Client” is used to refer to the entity that is ultimately collecting the payment through the Integrating System by way of a payer.

Configuration Values

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.

System Level

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.

Client Specific

Impersonation Key – 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
Authentication Required for this step: API Public Key and Impersonation Key.

The first step is to create a “token” which is a saved payment method representing ACH or credit card information. Once a token is created, the token can be reused for an unlimited number of payment transactions.

The key to securely creating the payment token is to use the ePayPolicy-hosted Javascript to POST the sensitive payment information to ePayPolicy’s servers. The Javascript will callback to a method sending either a user-friendly error message or an identifier representing the token.

IMPORTANT: Only the token Id, and not the sensitive payment information, should be POSTed back to the Integrating System.

Sample HTML for creating the token can be found here.

Step 2: Validate the Token
Authentication Required for this step: API Key, API Secret, and Impersonation Key

The server should validate the token by executing a GET /tokens/{id} once the token Id is POSTed to the server. If the token is valid, the API will return with values such as the payment method (ACH, Visa, etc), the last 4 digits of the account number, and other details.

The API documentation can be found here.

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

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

The token can be used to execute the payment transaction. 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.

 

To return to the general integration page click here