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

API Endpoint: (POST) https://api.epaypolicy.com:443/api/v1/tokens
Authentication Required: API Public Key (and Impersonation Key if applicable)
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.
Below is a sample request body for creating a token:

{
  "payer": "Test Payer",
  "emailAddress": "test@example.com",
  "creditCardInformation": {
    "accountHolder": "Test Payer",
    "cardNumber": "4242424242424242",
    "cvc": "999",
    "month": "12",
    "year": 2022,
    "postalCode": "78744"
  },
  "attributeValues": {
    "invoiceNumber": 1234
  }
}

On a successful token creation, you will receive a 201 response, with the tokenId in the location header. If there is a validation error with the payment information provided (i.e. invalid month/year, invalid CC number, etc), you will receive a 400 response, with a friendly error message detailing what’s wrong. We do not validate the payment details ability to complete a payment until the transaction creation.
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

API Endpoint: (GET) https://api.epaypolicy.com:443/api/v1/tokens/{tokenId}
Authentication Required: API Key, API Secret (and Impersonation Key if applicable)
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)

API Endpoint: (GET) https://api.epaypolicy.com:443/api/v1/transactionFees?amount={transactionAmount}
Authentication Required: 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

API Endpoint: (POST) https://api.epaypolicy.com:443/api/v1/transactions
Authentication Required: API Key, API Secret (and Impersonation Key if applicable)
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.