Introduction


The EpicPay Gateway Web Service API is a web service that allows third-party applications to process transactions through the EpicPay Gateway system. The range of processing scenarios (sale, authorize, credit, etc.) enable a flexible and powerful way to implement custom business logic.

The EpicPay Gateway Web Service API implements the REST architecture style. Request and response messages, including errors, are in JSON formats.

 

Intended Audience

This document is intended for developers who want to understand and implement the EpicPay Gateway Web Service API.

 

API Version and BaseURL

This documentation is for EpicPay Gateway API Version 1.0

BaseURL

 https://api.epicpay.com/payment/v1/

Note: For Sandbox testing, use the BaseURL provided in the Sandbox section.

 

API Keys

Before you can use this API, you must first generate an API Key for one your Terminals.

To generate an API Key for a Terminal, go to the EpicPay Gateway Virtual Terminal and log in using your Admin account credentials. Once you log in, use the Menu on the left to Navigate to Admin -> Manage API Keys. From the Manage API Keys page, click the Add Key button located near the top of the page. On the "Add New API Key" window, select the appropriate terminal then click the Add button. The window will update when the key has been successfully added. Download the password file using the Download Password File button, or copy the credentials and paste them somewhere safe. Once you have the API Key ID and Password, click the Close button to close the window.


Note: Once the "Add New API Key" window is closed, you will not be able to retrieve your Password for this key. Please ensure that your password is kept in a safe and secure location.
Note: The same API key can be used to access both the Payment and Reporting APIs.  

SSL Certification

  • All requests must be made over SSL.

Sandbox


The EpicPay Gateway Sandbox was designed for developers to test the EpicPay Gateway. While testing the API, use the BaseURL in the "Sandbox API" section below. After you have confirmed that your test requests work properly on the sandbox, simply update your API Key ID and Password to use an API Key for a Production Terminal, and change the URL of your requests to the Production BaseURL (See the "Introduction" section above).

 

Sandbox Registration

To use the Sandbox, you will need to Register a new Sandbox Account.

Once you have received your Sandbox User Account credentials, you will need to configure your Sandbox Terminal before you can use the Sandbox API.

 

Sandbox API Keys

Before you can use the Sandbox API, you must first generate an API Key for one your Sandbox Terminals.

To generate an API Key for a Sandbox Terminal, go to the EpicPay Gateway Sandbox Virtual Terminal and log in using your Sandbox User Account credentials (which you should have set up in the previous step: "Sandbox Registration". Once you log in, use the Menu on the left to Navigate to Admin -> Manage API Keys. From the Manage API Keys page, click the Add Key button located near the top of the page. On the "Add New API Key" window, select the appropriate terminal then click the Add button. The window will update when the key has been successfully added. Download the password file using the Download Password File button, or copy the credentials and paste them somewhere safe. Once you have the API Key ID and Password, click the Close button to close the window. Note: Once the "Add New API Key" window is closed, you will not be able to retrieve your Password for this key. Please ensure that your password is kept in a safe and secure location.

 

Sandbox API Version and BaseURL

The current Sandbox version is Version 1.0

BaseURL (Sandbox)

https://sandbox-api.epicpay.com/payment/v1/

 

Sandbox Virtual Terminal (Web Application)

Note: This is NOT the Sandbox API BaseURL. See "Sandbox API Version and BaseURL" above.

Sandbox Virtual Terminal: https://sandbox-vt.epicpay.com/

Authentication


To use the EpicPay Gateway Web Service API, you will need to provide credentials for one of your terminals with each request. They are:

  • API Key ID: This value identifies the Merchant and Terminal under which the transaction will be processed.
  • Password: Authenticates the EpicPay Gateway Web Service API request. This value should not be exposed to the public.

These credentials should be submitted as HTTP Basic Authentication username and password values.

Note: You will not be able to use the same credentials for Sandbox and Production environments because you will use a different terminal for each environment.

Note: The second part of the One-Time Tokenization process requires a different authentication method than the one shown here.

Transactions


Use this method for all types of non-recurring transactions, including 'sale', 'authorize', 'capture', 'credit', and 'void'. For proper implementation of each type, see the sections Sale/Authorize Transactions and Capture/Credit/Void Transactions below. For proper implementation of Sale/Authorize Transaction using a Token or Wallet, see Transactions Using Tokens and Transactions Using a Wallet below.

Sale/Authorize Transactions:

Transactions of types: "Sale" and "Authorize" use the same format, but with different values for the "transaction_type" property.

  • URL

BaseURL/authorize

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • amount:[Integer] Transaction amount in cents.

    • currency:[String] Three-letter ISO currency code representing the currency in which the payment was made.

    • method:[String] A payment method to use for the payment. If a wallet item is used, it must belong to the merchant.

    • transaction_type:[String] The type of transaction to perform.

    Conditionally Required:

    • sec_code:[String] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions (Required if "method" is 'echeck').

    • bank_account:[Object] The Bank Account Object (Required if "method" is 'echeck').

    • credit_card:[Object] The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').

    • wallet:[Object] The Wallet Object (Required if "method" is 'wallet').

    • token:[Object] The Payment Token Object (Required if "method" is 'card_token' or 'echeck_token').

    • epic_token:[Object] The Epic Token Object (Required if "method" is 'epic_token').

    • billing_address:[Object] The Billing Address Object (If "method" is 'credit_card', 'card_track', 'card_token', or when using a wallet token or checkout token of type: credit card, your terminal may require Address Verification (AVS), in which case you will be required to provide address or postal_code. Otherwise, this object is optional.)

    Optional:

    • client_transaction_id:[String] A client-defined value that can be used to internally identify the transaction request. This value is passed through the Gateway unmodified and may be searched in the Virtual Terminal. It is not passed on to the financial institution. Format: [A-Za-z0-9-]{0,40}.

    • client_order_id:[String] A client-defined value that can be used to internally identify the order. It could be a purchase order or invoice number. This value is passed through the Gateway unmodified and be searched in the Virtual Terminal. It is not passed on to the financial institution. Format: [A-Za-z0-9-_#]{0,40}.

    • client_customer_id:[String] A client-defined value that can be used to internally identity the customer. This value is passed through the Gateway unmodified and may be searched in the Virtual Terminal. It is not passed on to the financial institution. Format: [A-Za-z0-9-_#]{0,40}.

    • entry_description:[String] A description of the purpose of the ACH transaction (e.g. “Purchase” or “Donation”). This will appear on the consumer’s bank account statement (Applicable only when “method” is 'echeck', 'echeck_token' or 'wallet' of type eCheck).

    • is_test:[String] For testing only. When this property is set to 'true', the transaction will be in "TEST MODE". Transactions in "TEST MODE" will not be Authorized or Settled, but will return a valid response. (Values: 'true', 'false'; Default 'false')  

Payment Request Variables


Variable Description
transaction_type String The type of transaction being performed (Values: 'sale', 'authorize').
amount Integer Payment amount in cents (Value cannot be negative).
currency String[3] Three-letter ISO currency code representing the currency in which the payment was made.
client_transaction_id String[40] (Optional) A client-defined value that can be used to internally identify the transaction request. This value is passed through the Gateway unmodified and may be searched in the Virtual Terminal. It is not passed on to the financial institution. Format: [A-Za-z0-9-]{0,40}.
client_order_id String[40] (Optional) A client-defined value that can be used to internally identify the order. It could be a purchase order or invoice number. This value is passed through the Gateway unmodified and be searched in the Virtual Terminal. It is not passed on to the financial institution. Format: [A-Za-z0-9-_#]{0,40}.
client_customer_id String[40] (Optional) A client-defined value that can be used to internally identity the customer. This value is passed through the Gateway unmodified and may be searched in the Virtual Terminal. It is not passed on to the financial institution. Format: [A-Za-z0-9-_#]{0,40}.
method String A payment method to use for the payment. If a wallet item is used, it must belong to the merchant.
credit_card Object The Credit Card Object (Required when "method" is 'credit_card').
bank_account Object The Bank Account Object (Required when "method" is 'echeck').
wallet Object The Wallet Object (Required when "method" is 'wallet').
token Object The Payment Token Object (Required when "method" is 'card_token' or 'echeck_token').
sec_code String[3] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions (Required when "method" is 'echeck').
billing_address Object The Billing Address Object (If "method" is 'credit_card', 'card_track', 'card_token' or 'wallet' of type credit card, your terminal may require Address Verification (AVS), in which case you will be required to provide address or postal_code. Otherwise, this object is optional).
entry_description String[10] A description of the purpose of the ACH transaction (e.g. “Purchase” or “Donation”). This will appear on the consumer’s bank account statement (Applicable only when “method” is 'echeck', 'echeck_token' or 'wallet' of type eCheck).
is_test String (Optional) For testing only. When this property is set to 'true', the transaction will be in "TEST MODE". Transactions in "TEST MODE" will not be Authorized or Settled, but will return a valid response. (Values: 'true', 'false'; Default 'false')

 

Example Transaction Request (Credit Card)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"credit_card",
  "transaction_type":"authorize",
  "credit_card":{
    "card_number":"4111111111111111",
    "card_holder_name":"Bob Smith",
    "exp_month":"01",
    "exp_year":"2018",
    "cvv":"123"
  },
  "billing_address":{
    "postal_code":"12345"
  }
}

 

Example Transaction Request (eCheck)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"echeck",
  "transaction_type":"sale",
  "sec_code":"web",
  "entry_description": "Donation",
  "bank_account":{
    "account_type":"personal_checking",
    "routing_number":"211370545",
    "account_number":"01234567890123",
    "account_holder_name":"Bob Smith"
  }
}

Note: The SEC code will vary based on the account type and whether the transaction is initiated over the internet or not. For personal checking and savings accounts, WEB should be used for internet transactions and PPD for non-internet. Business accounts should use CCD for all scenarios. For more information on SEC codes, please consult Appendix 4.

 

Example Transaction Curl

curl {BaseURL}/authorize
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "amount":"111",
      "currency":"usd",
      "method":"wallet",
      "transaction_type":"sale",
      "wallet": "{\"wallet_id\":\"2949030ce5084a11a0dec92db3ce9311\"}" }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

Transactions Using Tokens:

Both one-time tokens and multi-use tokens can be used to process Sale and Authorize transactions. Both token types use the same request format, but with a different "transaction_type".

 

Example Request (Authorize: One-Time-Use Credit Card Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"card_token",
  "transaction_type":"authorize",
  "token":{
    "token_type":"epicpay",
    "token_number":"1000933766171111",
    "account_holder_name":"Bob Smith",
    "exp_month":"12",
    "exp_year":"19",
    "cvv":"1234"
  }
}

 

Example Request (Sale: One-Time-Use eCheck Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"echeck_token",
  "transaction_type":"sale",
  "sec_code":"web",
  "token":{
    "token_type":"epicpay",
    "token_number":"10005555555550123",
    "account_holder_name":"Bob Smith"
  }
}

 

Example Request (Authorize: Multi-Use Credit Card Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"card_token",
  "transaction_type":"authorize",
  "token":{
  "token_type":"epicpay",
    "token_number":"2000000059501111",
    "account_holder_name":"Bob Smith",
    "exp_month":"12",
    "exp_year":"19",
    "cvv":"1234"
  }
}

 

Example Request (Sale: Multi-Use eCheck Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"echeck_token",
  "transaction_type":"sale",
  "sec_code":"web",
  "token":{
    "token_type":"epicpay",
    "token_number":"20000000059500123",
    "account_holder_name":"Bob Smith"
  }
}

 

Example Curl (eCheck Wallet Item)

curl {BaseURL}/authorize
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "amount":"111",
      "currency":"usd",
      "method":"echeck_token",
      "transaction_type":"sale",
      "sec_code":"web",
      "token": "{
        \"token_type\":\"epicpay\",
        \"token_number\":\"20000000059500123\",
        \"account_holder_name\":\"Bob Smith\"
      }"
   }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

 

Example Request (Sale: Credit Card Epic Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"9995",
  "currency":"usd",
  "method":"epic_token",
  "transaction_type":"sale",
  "epic_token":{
    "token_type":"card_token",
    "token_data":"11000000000001234",
    "account_holder_name":"John Smith",
    "exp_month":"12",
    "exp_year":2024",
    "cvv":"123"
  },
  "billing_address":{
    "first_name":"John",
    "last_name":"Smith",
    "postal_code":"12345"
  }
}

 

Example Request (Sale: eCheck Epic Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"9995",
  "currency":"usd",
  "method":"epic_token",
  "transaction_type":"sale",
  "epic_token":{
    "token_type":"echeck_token",
    "token_data":"10000000000007890",
    "account_holder_name":"John Smith"
  },
  "billing_address":{
    "first_name":"John",
    "last_name":"Smith",
    "postal_code":"12345"
  }
}

 

Example Request (Sale: Checkout Epic Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"9995",
  "currency":"usd",
  "method":"epic_token",
  "transaction_type":"sale",
  "epic_token":{
    "token_type":"checkout_token",
    "token_data":"abc.123.xyz==",
    "account_holder_name":"Bob Smith"
  },
  "billing_address":{
    "first_name":"John",
    "last_name":"Smith",
    "postal_code":"12345"
  }
}

Transactions Using a Wallet:

Each customer in the Customer Vault has a Virtual Wallet that can be used to store payment account information (including credit cards and bank accounts) for that customer. Each payment account stored in a wallet has an associated WalletID which can be used to process transactions.

 

Example Request (eCheck Wallet Item)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"wallet",
  "transaction_type":"sale",
  "sec_code":"web",
  "wallet":{
    "wallet_id":"6473A04E7F6147549D840CF7E46EC6CB",
  }
}

 

Example Curl (eCheck Wallet Item)

curl {BaseURL}/authorize
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "amount":"111",
      "currency":"usd",
      "method":"wallet",
      "transaction_type":"sale",
      "wallet": "{\"wallet_id\":\"2949030ce5084a11a0dec92db3ce9311\"}" }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

 

Example Request (eCheck Wallet using Epic Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"9995",
  "currency":"usd",
  "method":"epic_token",
  "transaction_type":"sale",
  "epic_token":{
    "token_type":"wallet_token",
    "token_data":"abc123def789"
  },
  "billing_address":{
    "first_name":"John",
    "last_name":"Smith",
    "postal_code":"12345"
  }
}

 

Example Request (Credit Card Wallet using Epic Token)

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"9995",
  "currency":"usd",
  "method":"epic_token",
  "transaction_type":"authorize",
  "epic_token":{
    "token_type":"wallet_token",
    "token_data":"abc123def789",
    "cvv":"123"
  },
  "billing_address":{
    "first_name":"John",
    "last_name":"Smith",
    "postal_code":"12345"
  }
}

Capture/Credit/Void Transactions:

Transactions of types: "Capture", "Credit", and "Void" use the same format, but with different values for the "transaction_type" property. Each of these types of requests must include (as part of the URL) the transaction_id of the parent transaction, which you can obtain from the previous transaction's Response Object.

  • URL

    BaseURL/authorize/transaction_id

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • amount:[Integer] Transaction amount in cents.

    • transaction_type:[String] The Type of Transaction to perform.

 

Payment Modification Request Variables


Variable Description
transaction_type String The type of transaction being performed. Values: 'capture', 'void', 'credit'
amount Integer Payment amount in cents. Values: Positive integer or zero.
client_transaction_id String[40] (Optional) A client-defined value that can be used to internally identify the transaction request. This value is passed through to the Gateway unmodified and may be searched in the Merchant Virtual Terminal. It is not passed on to the financial institution.
transaction_id String[40] Unique transaction id returned by EpicPay Gateway in the response of the previous payment request (i.e. 'sale' or 'authorize'). To credit a captured transaction, use the transaction_id from the "Capture" request.

 

Example Request (Capture)

POST {BaseURL}/authorize/290487234 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "transaction_type":"capture",
  "amount":"111"
}

 

Example Request (Credit)

POST {BaseURL}/authorize/290423739 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "transaction_type":"credit",
  "amount":"495"
}

 

Example Request (Void)

POST {BaseURL}/authorize/290499283 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "transaction_type":"void",
  "amount":"333"
}

 

Example Curl

curl {BaseURL}/authorize/290487234
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "transaction_type":"capture",
      "amount":"111" }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

Transaction Sale / Authorize Response

All transactions for Sale/ Authorize will return the same response object.

 

Payment Response Variables for Sale / Authorize


Variable Description
status Object Status of the API Request.
  response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
  reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
  reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
  payment Object
    transaction_id String[40] A unique identifier to associate with a payment request. This id is required to modify (i.e. 'capture', 'void', or 'credit') the payment later.
    authorization_number String Authorization number returned by the cardholder's financial institution when a transaction has been approved.
    avs_code String Result code for Address Verification(AVS).
    cvv_code String Result code for CVV Authentication (Returned from the bank - will be blank if CVV is not supported.)
    transaction_type String The type of transaction performed (Returned unmodified).
    amount Integer Payment amount in cents (Returned unmodified).
    currency String[3] Three-letter ISO currency code representing the currency in which the payment was made (Returned unmodified).
    client_transaction_id String[40] A client-defined value that can be used to internally identify the transaction (Returned unmodified).
    method String The payment method (Returned unmodified).
    credit_card Object The Credit Card Object along with the card_type. (Returned with sensitive fields removed or masked).
    bank_account Object The Bank Account Object (Returned with sensitive fields removed or masked).
    wallet Object The Wallet Object (Returned with sensitive fields removed or masked).
    token Object The Payment Token Object (Returned with sensitive fields removed or masked).
    billing_address Object The Billing Address Object (Returned unmodified).

 

Example Response (Sale: Credit Card)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": "XYZ12020",
      "transaction_id": "38141",
      "method": "credit_card",
      "authorization_number": "123457",
      "avs_code": "Y",
      "cvv_code": "M",
      "credit_card": {
        "card_type": "visa",
        "card_number": "411111****1111",
        "card_holder_name": "Bob Smith",
        "exp_month": "01",
        "exp_year": "2018"
      },
      "billing_address": {
        "first_name": "Bob",
        "last_name": "Smith",
        "postal_code": "12345"
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      }
    }
  }
}

 

Example Response (Sale: One-Time-Use eCheck Token)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": "XYZ12021",
      "transaction_id": "38190",
      "method": "echeck_token",
      "token": {
        "token_type": "epicpay",
        "token_number": "22000000055878123",
        "account_holder_name": "Bob Smith"
      }
    }
  }
}

(Note: When a one-time-use token is used, a multi-use token is returned.)

 

Example Response (Sale: Multi-Use eCheck Token)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
   },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": "XYZ12024",
      "transaction_id": "38174",
      "method": "echeck_token",
      "token": {
        "token_type": "epicpay",
        "token_number": "22000000055066992",
      "account_holder_name": "Bob Smith"
      }
    }
  }
}

 

Example Response (Sale: One-Time-Use Credit Card Token)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
   },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": null,
      "transaction_id": "38240",
      "method": "card_token",
      "authorization_number": "123457",
      "avs_code": "Y",
      "cvv_code": "M",
      "billing_address": {
        "postal_code": "12345"
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      }
    }
  }
}

(Note: When a one-time-use token is used, a multi-use token is returned.)

 

Example Response (Sale: eCheck Wallet)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
   },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": null,
      "transaction_id": "38315",
      "method": "wallet",
      "wallet": {
        "wallet_id": "D9CCF647FB0B4D0683DD51DA07D76C4A"
      }
    }
  }
}

 

Example Response (Sale: Checkout - Credit Card)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 9995,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": "XYZ12020",
      "client_customer_id": "1",
      "transaction_id": "38141",
      "customer_id":"ABC123",
      "method": "credit_card",
      "authorization_number": "123457",
      "avs_code": "Y",
      "cvv_code": "M",
      "credit_card": {
          "card_type": "visa",
          "card_number": "411111****1111",
          "card_holder_name": "Bob Smith",
          "exp_month": "01",
          "exp_year": "2018"
      },
      "billing_address": {
        "first_name":"John",
         "last_name":"Smith",
         "postal_code": "12345"
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      }
    }
  }
}

 

Example Response (Sale: Credit Card - TEST MODE)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved-TEST MODE"
  },
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "usd",
      "client_transaction_id": "XYZ12020",
      "transaction_id": "38141",
      "method": "credit_card",
      "authorization_number": "123457",
      "avs_code": "Y",
      "cvv_code": "M",
      "credit_card": {
        "card_type": "visa",
        "card_number": "411111****1111",
        "card_holder_name": "Bob Smith",
        "exp_month": "01",
        "exp_year": "2018"
      },
      "billing_address": {
        "first_name": "Bob",
        "last_name": "Smith",
        "postal_code": "12345"
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      }
    },
  }
}

 

Transaction Void / Capture / Refund Response

All transactions for Void/Capture/Refund will return the same response object.

 

Payment Response Variables for Void / Capture / Refund


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   payment Object
     transaction_id String[40] A unique identifier to associate with a payment request. This id is required to modify (i.e. 'capture', 'void', or 'credit') the payment later.
     transaction_type String The type of transaction performed (Returned unmodified).
     amount Integer Payment amount in cents (Returned unmodified).
     currency String[3] Three-letter ISO currency code representing the currency in which the payment was made (Returned unmodified).
     client_transaction_id String[40] A client-defined value that can be used to internally identify the transaction (Returned unmodified).

  Example Response (Capture)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 450

{
  "result": {
   "payment": {
     "transaction_type": "capture",
     "currency": "usd",
     "amount": 111,
     "client_transaction_id": null,
     "transaction_id": "90035"
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "001",
    "reason_text": "Received"
  }
}

 

Example Response (Refund)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 450

{
  "result": {
   "payment": {
     "transaction_type": "credit",
     "currency": "usd",
     "amount": 50,
     "client_transaction_id": null,
     "transaction_id": "90076"
   }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "001",
    "reason_text": "Received"
  }
}

 

Example Response (Void)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 450

{
  "result": {
   "payment": {
     "transaction_type": "void",
     "amount": 100,
     "currency": "usd",
     "client_transaction_id": null,
     "transaction_id": "90050"
   }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "001",
    "reason_text": "Received"
  }
}

Tokenization


Tokenization refers to the process of generating a unique code (called a "token") that will identify a customer's payment account information within the EpicPay Gateway. These tokens allow merchants to process transactions via the EpicPay Gateway API Web Service without storing customer account information in the merchant's database. Tokenization protects both merchants and customers from potential security breaches by preventing sensitive customer account details from reaching the merchant. Unlike credit card numbers, tokens can be stored in the merchant's database in plaintext, eliminating the need for expert-level security measures, including encryption, access control, network and physical security parameters, and periodic penetration testing and vulnerability screening. Merchants who use tokenization will find it easy to meet all the requirements of PCI DSS, even when offering recurring billing plans within their own applications.

The EpicPay Gateway provides three types of token: One-Time-Use Tokens, Multi-Use Tokens, and Wallets. Any token type can be generated for any of the two main payment methods: Credit Card and eCheck(ACH) - See the Token Formats Table for more details.

 

Token Formats:

Token Types One-time-use Multi-Use WalletID
Credit Card 16 numeric digits, starts with 1000 16 numeric digits, starts with 1100 32 hexadecimal digits
eCheck 17 numeric digits, starts with 1000 17 numeric digits, starts with 1100 32 hexadecimal digits

 

Multi-Use Tokens

Multi-Use Tokens can be used in place of an actual account number when processing transactions. This allows the merchant to offer convenient services, such as recurring billing and easy payment for repeat customers, without the need to store credit card or bank account numbers. Tokens can be safely stored in plaintext without encryption or other rigorous security measures.

Multi-Use Tokens can be generated in one of two ways:

  1. Whenever a "sale" or "authorize" transaction is approved via the EpicPay Gateway API a Multi-Use Token be returned as part of the transaction Response Object. The type of token returned after a successful transaction varies depending on the payment method used. See the Token Types Returned table below for more details.

  2. Multi-Use Tokens can be generated without a prior transaction, using the RegisterToken method.

 

Token Types Returned:

Method Token Returned
Credit Card NEW Multi-Use Token
eCheck NEW Multi-Use Token
One-Time Token NEW Multi-Use Token
Multi-Use Token SAME Multi-Use Token
Wallet SAME WalletID

 

One-time-use Tokens

One-time-use tokens allow a merchant to process transactions on a website or application without ever storing or even encountering credit card or bank account numbers on their servers. These tokens can be generated during the checkout process on your e-commerce website or application, and are designed to be used only for a single transaction. To use one-time-use tokens, you must first obtain a JSON Web Token (JWT). JWT's will expire within a short time frame (~10 minutes in the current version), so a new JWT must be requested via server-side every time a customer encounters a checkout page. The JWT should then be passed from the server-side to the client-side checkout page. When the user has entered all their payment information and submits the form, you must send the JWT, the payment method, and the account number using a client-side asynchronous method (e.g. AJAX) to call the RegisterOneTimeToken method before the data is sent to your server. The method will return a One-Time-Use Token, which you will use to replace the account number provided by the user before the form is finally submitted to your server for processing/storage.

Multi-Use Tokenization


This section explains how to obtain Multi-Use Tokens without placing a transaction. For general information about these tokens, see: Tokenization Introduction.

  • URL

BaseURL/RegisterToken

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • method:[String] A payment method to use for the tokenization (Values: 'credit_card', 'card_track', 'echeck', 'card_token', 'echeck_token').

    Conditionally Required:

    • credit_card:[Object] The Credit Card Tokenization Object (See table below) (Required if "method" is 'credit_card' or 'card_track').

    • bank_account:[Object] The Bank Account Tokenization Object (See table below) (Required if "method" is 'echeck').

    • token:[Object] The One-Time Token Object (See table below) (Required if "method" is 'card_token' or 'echeck_token').
               Note: The token object passed must be a One-Time-Use token only.

 

Multi-Use Tokenization Request Variables


Variable Description
method String A payment method to use for the tokenization (Values: 'credit_card', 'card_track', 'echeck', 'card_token', 'echeck_token').
credit_card Object The Credit Card Tokenization Object (See table below) (Required if "method" is 'credit_card' or 'card_track').
bank_account Object The Bank Account Tokenization Object (See table below) (Required if "method" is 'echeck').
token Object The One-Time Token Object (See table below) (Required if "method" is 'card_token' or 'echeck_token').
     Note: The token object passed must be a One-Time-Use token only.

 

Credit Card Tokenization Object


Use this if "method" is 'credit_card' or 'card_track'.

Property Description
card_number String Credit card number.
card_holder_name String[50] (Required) Cardholder's name.
exp_month String (Required) Expiration month. (2-digit: "01" - "12")
exp_year String (Required) Expiration year. (4-digit)
    -OR- (Omit the properties above if you provide a 'card_track'.)
card_track String[350] The data from track 1 of a credit card's magnetic stripe (acquired using a credit card reader).

 

Bank Account Tokenization Object


Use this if "method" is 'echeck'.

Property Description
account_holder_name String[50] Bank account holder's name.
account_type String Bank account types. (Values: 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
routing_number String[9] 9-digit Bank routing number. Must pass Mod 10 validation check.
account_number String[17] Bank account number.

 

One-Time Token Object


Use this if "method" is 'card_token' or 'echeck_token'.

Property Description
token_type String Token type. (Values: 'epicpay', 'litle')
token_number String Token number.
account_holder_name String[50] (Required) Account holder's name.
exp_month String (Required for Credit Card tokens) Expiration month. (2-digit: "01" - "12")
exp_year String (Required for Credit Card tokens) Expiration year. (4-digit)

 

Example Multi-Use Tokenization Request (Credit Card)

POST {BaseURL}/registertoken HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"credit_card",
  "credit_card":{
    "card_number":"4111111111111111",
    "card_holder_name":"Bob Johnson",
    "exp_month":"12",
    "exp_year":"2022"
  }
}

 

Example Multi-Use Tokenization Request (Credit Card Swipe)

POST {BaseURL}/registertoken HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"card_track",
  "credit_card":{
    "card_track":"%B60110009669337^NETWORK/DISCOVER          ^181020110152309102?;60110092669337=181021000152309102?"
  }
}

 

Example Multi-Use Tokenization Request (eCheck)

POST {BaseURL}/registertoken HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"echeck",
  "bank_account":{
    "account_holder_name":"Bob Johnson",
    "account_type":"personal_checking",
    "routing_number":"211370545",
    "account_number":"01234567890123"
  }
}

 

Example Multi-Use Tokenization Request (One-time Card token)

POST {BaseURL}/registertoken HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"card_token",
  "token":{
    "token_type":"epicpay",
    "token_number":"211370545",
    "account_holder_name":"Bob Johnson",
    "exp_month":"12",
    "exp_year":"2022"
  }
}

 

Example Multi-Use Tokenization Request (One-time eCheck token)

POST {BaseURL}/registertoken HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"echeck_token",
  "token":{
    "token_type":"epicpay",
    "token_number":"211370545",
    "account_holder_name":"Bob Johnson"
  }
}

 

Example Multi-Use Tokenization Curl (Credit Card)

curl {BaseURL}/registertoken
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "method":"credit_card",
      "credit_card": "{
        \"card_number\":\"4111111111111111\",
        \"card_holder_name\":\"Bob Johnson\",
        \"exp_month\":\"12\",
        \"exp_year\":\"2022\"
      }"
    }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

 

Multi-Use Token Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   token Object
     token_type String Token type. (Values: 'epicpay', 'litle')
     token_number String Token number.

 

Example Multi-Use Tokenization Response (eCheck)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "result": {
    "token": {
      "token_type": "epicpay",
      "token_number": "22000000055878123"
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

 

Example Multi-Use Tokenization Response (Credit Card)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "result": {
   "token": {
     "token_type": "epicpay",
     "token_number": "1100000025451111"
    }
   },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

One-Time Tokenization


This section explains how to obtain One-time-use tokens. For general information about these tokens, see: Tokenization Introduction.

One-time tokenization requires calling two separate API methods in order. The first API method to call is RequestJWT, and this call must be executed via server-side code; If you call this method from client-side code, your API credentials will be exposed to the end-user. Once you have received the JWT token from the first step, you will use that token to call the second method, "RegisterOneTimeToken", via client-side code (e.g. JavaScript). The second part of the process can be automated using the One-Time Tokenization Library provided by EpicPay, as long as your application supports JavaScript.

 

Authorization of One-Time Tokenization Requests

The advantage of using one-time tokenization is that you will remain entirely outside of the scope of PCI compliance; your servers will never come in contact with credit card numbers or other protected data. To accomplish this, the call to the one-time-tokenization API method must come from within your application's client-side code. However, calling from client-side presents a challenge for authentication: The basic authentication method used throughout the EpicPay Gateway would expose your API credentials to the public if used for a client-side API call.

To avoid exposing your API credentials, the one-time tokenization request uses bearer authentication instead of basic authentication. To use bearer authentication, you will first need to make a separate API call via secure server-side code to obtain a JSON Web Token (JWT). The JWT that is returned from this call is the token you will use for bearer authentication in the one-time tokenization request. That JWT should then be passed from your server-side to your client-side, and stored in a hidden input until the one-time-tokenization method is called. Typically, a JWT should be requested when the consumer first hits the checkout (or donate) page.

 

Process Overview

Part 1 (Requesting a JWT):

  1. After the end-user attempts to navigate to a checkout or donate page, but just before the page is served, make a server-side call to "RequestJWT" to obtain a JSON Web Token.
  2. Pass the JWT to the client-side code and store it in a hidden input element on your payment form.

Part 2 (Requesting a One-Time-Use Token):

  1. When the user clicks the payment form's submit button, do not post the data to your server right away. Instead, make a client-side asynchronous call to obtain a One-Time-Use Token.
  2. Use the token value returned in the "RegisterOneTimeToken" response to replace the value of the account number input element. In other words, replace the real account number with the token value.
  3. Post the form data to your server.
  4. Verify that your server received a token instead of a real card number.

 

Part 1 - JWT Token Request


This method must be called using server-side code in order to protect your API credentials. The token generated in this step is a JWT, which is not the same as a One-Time-Use Token. However, you must use the JWT obtained from this step when you request a One-Time-Use Token in the next step.

  • URL:

BaseURL/requestjwt

  • Method:

    POST

  • Authorization:

    Basic

API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • ip:[String] The Customer's Public IP Address. This IP Address must match the Sender's IP Address of any subsequent requests that use JWT for authorization. If the IP Addresses do not match, you will receive an "Invalid Token" error.

    Note: While testing, you can get your public ip address via a simple api call to https://www.ipify.org/.

 

JWT Token Request Variables


Variable Description
ip String The Customer's Public IP Address. This IP Address must match the Sender's IP Address of any subsequent requests that use JWT for authorization. If the IP Addresses do not match, you will receive an "Invalid Token" error. While testing, please be sure that you are using your Public IP Address. Using a private IP Address will create an invalid JWT.

 

Example JWT Token Request

POST {BaseURL}/RequestJWT HTTP/1.1
Authorization: Basic czZCaGfSa3F0Mzpn3DF
Content-Type: application/json

{
  "ip":"198.51.100.0"
}

 

Example JWT Token Curl

curl -X POST {BaseURL}/RequestJWT
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{"ip":"198.51.100.0"}'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

 

JWT Token Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   jwt String The token used for authenticating a one-time tokenization request.

Example JWT Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 120

{
  "status": {
    "response_code": "Received",
    "reason_code": "000",
    "reason_text": "Received"
  },
  "result": {
    "jwt": "eyJhbGciOm51bGwsInR5cCI6.UQiOiJiNDc0Nzdi.bGwUiOGiiNDc0NnR=="
  }
}

 

Part 2 - One-Time-Use Token Request


Note: This method must be implemented using an asynchronous call, which executes after the user fills out the checkout form and submits, but before the data is sent to your server for storing. Once you have obtained the One-Time-Use Token, use it to replace the actual account number typed by the customer before sending the form data to your server. This part of the process can be automated using the "One-Time Tokenization Library" provided by EpicPay, as long as your application supports JavaScript. For more information, see One-Time Tokenization Library.

  • URL:

BaseURL/RegisterOneTimeToken

  • Method:

    POST

  • Authorization:

    Bearer

JWT (Token from Step 1)

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • method:[String] A payment method to use for the tokenization. (Values: 'echeck', 'credit_card').

    • account_number:[String] Credit Card or Bank Account Number.

    Conditionally Required: (Required if "method" is 'eCheck').

    • bank_account_type:[String] The type of bank account used (Values: 'Personal_Checking', 'Business_Checking', 'Personal_Savings', 'Business_Savings').

    • routing_number:[String] The bank account's ABA routing transit number (9 digits).

 

One-Time-Use Token Request Variables


Variable Description
method String A payment method to use for the tokenization. (Values: 'echeck', 'credit_card').
account_number String(4-17 digits) Credit Card or Bank Account Number.
bank_account_type String The type of bank account used (Required if "method" is 'eCheck'. Values: 'Personal_Checking', 'Business_Checking', 'Personal_Savings', 'Business_Savings').
routing_number String(9 digits) The bank account's ABA routing transit number (Required if "method" is 'eCheck').

Example One-Time-Use Token Request (Credit Card)

POST {BaseURL}/RegisterOneTimeToken HTTP/1.1
Authorization: bearer eyJhbGciOm51bGwsInR5cCI6.UQiOiJiNDc0Nzdi.bGwUiOGiiNDc0NnR==
Content-Type: application/json

{
  "method":"credit_card",
  "account_number":"4111111111111111"
}

 

Example One-Time-Use Token Request (eCheck)

POST {BaseURL}/RegisterOneTimeToken HTTP/1.1
Authorization: bearer eyJhbGciOm51bGwsInR5cCI6.UQiOiJiNDc0Nzdi.bGwUiOGiiNDc0NnR==
Content-Type: application/json

{
  "method":"eCheck",
  "account_number":"01234567890123",
  "bank_account_type":"Personal_Checking",
  "routing_number":"211370545"
}

 

Example One-Time-Use Token Curl

curl -X POST {BaseURL}/RegisterOneTimeToken
  -H "Content-Type: application/json"
  -H "Authorization: bearer eyJhbGciOm51bGwsInR5cCI6.UQiOiJiNDc0Nzdi.bGwUiOGiiNDc0NnR=="
  -d '{"method":"eCheck","account_number":"01234567890123","bank_account_type":"Personal_Checking","routing_number":"211370545"}'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

 

One-Time-Use Token Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   token Object
     token_type String Token type. (Values: 'epicpay', 'litle')
     token_number String Token number.

Example One-Time-Use Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 120

{
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  },
  "result": {
    "token": {
      "token_type": "epicpay",
      "token_number": "1000826810501111"
    }
  }
}

One-Time Tokenization Library


EpicPay provides a JavaScript library to simplify the process of requesting a one-time-use token. Simply embed the script on your checkout page and configure some mappings. The library will automatically configure each tokenization request, send the request, and replace the account number with the token received from the EpicPay Gateway Web Service. This library has no dependencies and can be used safely alongside custom scripts and libraries/frameworks such as jQuery, Angular, Node, etc.

 

Live Demos:

Each of these demo pages use the One-Time-Tokenization Library, but with different configurations. Click the "View the Code" button on each form to see how they are implemented. For more information on configuration, see the Configuration section below.

Reference the Library:

It is recommended that you reference the version of the script that is hosted on the EpicPay Api Server. To use the tokenization library, add a reference to the script in the head of your document. For testing, use the Sandbox Library Path. When you're ready to go live, switch to the Production Library Path.

Example 1 - Referencing the Sandbox Library:

<script src="https://sandbox-api.epicpay.com/payment/v1/scripts/EpicTokenize.min.js"></script>

 

Example 2 - Referencing the Production Library:

<script src="https://api.epicpay.com/payment/v1/scripts/EpicTokenize.min.js"></script>

 

Configuration:

After you reference the library, a small amount of configuration is required. The library doesn't know which form elements to use unless you specify that information. There are two mapping methods that you must choose from: the "Data-Attribute Method" or the "Mapping Method" (Note: choose only one method - a hybrid approach will not work). The "Data-Attribute Method" requires no JavaScript code (aside from the library reference), but you will need to edit the form's html. The "Mapping Method", on the other hand, requires you to add a small amount of javascript code, but you will not need to edit the form's html. Which option you should choose will depend on your team's coding preferences, your application's development phase, and other factors.

 

Configuration Option 1: The Data-Attribute Method

This method uses HTML5 Data Attributes to tell the Library which form elements to use. Simply reference the script within your form's <head>, and add the following data-attributes to page elements, as needed:

Data Attribute Place this attribute on... Requirement
data-epicpay-tokenize The <form> tag. Required
data-epicpay-submit The submit button (<input> or <button> tag). Required
data-epicpay-jwt The hidden <input> tag for the element that holds the JWT from step 1. Required
data-epicpay-credit_card_number The <input> tag for the element that holds the credit card number Conditional
(Required only if your checkout page accepts Credit Card payments)
data-epicpay-bank_account_number The <input> tag for the element that holds the bank account number. Conditional
(Required only if your checkout page accepts eCheck payments)
data-epicpay-routing_number The <input> tag for the element that holds the 9-digit ABA Routing Number. Conditional
(Required only if your checkout page accepts eCheck payments)
data-epicpay-bank_account_type The <select> tag for the element that holds the Account Type. Conditional
(Required only if your checkout page accepts eCheck payments)

Note: If your checkout page uses the same input element for both "credit card number" and "bank account number", place both data-epicpay-credit_card_number and data-epicpay-bank_account_number on that input. For proper implementation, see "Data-Attributes Method - Example 2").

 

Data-Attributes Method - Example 1 (Credit Card & eCheck w/ separate account number inputs):

<form data-epicpay-tokenize method="post" action="/APITester/ShowFormData">

    <input type="hidden" id="jwt" name="jwt" value="{{JWT.From.Step1}}" data-epicpay-jwt />

    ...

    Credit Card Number:
    <input type="text" id="creditCardNumber" name="creditCardNumber" data-epicpay-credit_card_number />

    Bank Account Number:
    <input type="text" id="bankAccountNumber" name="bankAccountNumber" data-epicpay-bank_account_number />

    Routing Number:
    <input type="text" id="routingNumber" name="routingNumber" data-epicpay-routing_number />

    Bank Account Type:
    <select id="bankType" name="bankType" data-epicpay-bank_account_type>
        <option value=""></option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>

    <button type="submit" data-epicpay-submit>Submit</button>

</form>

See a Live Demo of this Example

 

Data-Attributes Method - Example 2 (Credit Card & eCheck w/ single account number input):

<form data-epicpay-tokenize method="post" action="/APITester/ShowFormData">

    <input type="hidden" id="jwt" name="jwt" value="{{JWT.From.Step1}}" data-epicpay-jwt />

    ...

    Account Number:
    <input type="text" id="accountNumber" name="accountNumber" data-epicpay-credit_card_number data-epicpay-bank_account_number />

    Routing Number:
    <input type="text" id="routingNumber" name="routingNumber" data-epicpay-routing_number />

    Bank Account Type:
    <select id="bankType" name="bankType" data-epicpay-bank_account_type>
        <option value=""></option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>

    <button type="submit" data-epicpay-submit>Submit</button>

</form>

See a Live Demo of this Example

 

If your checkout pages allow only one type of payment method, you can safely leave off data-attributes related to the other payment method.

Data-Attributes Method - Example 3 (CreditCard-Only):

<form data-epicpay-tokenize method="post" action="/APITester/ShowFormData">

    <input type="hidden" id="jwt" name="jwt" value="{{JWT.From.Step1}}" data-epicpay-jwt />

    ...

    Credit Card Number:
    <input type="text" id="creditCardNumber" name="creditCardNumber" data-epicpay-account_number />

    <button type="submit" data-epicpay-submit>Submit</button>

</form>

 

Data-Attributes Method - Example 4 (eCheck-Only):

<form data-epicpay-tokenize method="post" action="/APITester/ShowFormData">

    <input type="hidden" id="jwt" name="jwt" value="{{JWT.From.Step1}}" data-epicpay-jwt />

    ...

    Bank Account Number:
    <input type="text" id="bankAccountNumber" name="bankAccountNumber" data-epicpay-account_number />

    Routing Number:
    <input type="text" id="routingNumber" name="routingNumber" data-epicpay-routing_number />

    Bank Account Type:
    <select id="bankType" name="bankType" data-epicpay-bank_account_type>
        <option value=""></option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>

    <button type="submit" data-epicpay-submit>Submit</button>

</form>

 

Configuration Option 2: The Mapping Method

The Mapping Method requires the developer to set up mappings within a small JavaScript Object. Create a property on the window called "EpicTokenize", which will contain a single property "FormElementIDs". FormElementIDs will have several properties, each of which will point to the ID of a page element.

The Mapping Object

<!-- Mapping Object -->
<script>
    window.EpicTokenize = {
        FormElementIDs: {
            //Properties will go here
        }
    }
</script>

 

Properties to include on the FormElementIDs object:

Property Requirement Set this equal to...
form_id Required The ID of the <form> element.
jwt_field_id Required The ID of the hidden <input> element containing the JWT from step 1.
submit_button_id Required The ID of the <button> or <input> element used to submit the form.
credit_card_number_field_id Conditional (Use only if your checkout page accepts Credit Card payments) The ID of the <input> element for the credit card number.
bank_account_number_field_id Conditional (Use only if your checkout page accepts eCheck payments) The ID of the <input> element for the bank account number.
routing_number_field_id Conditional (Use only if your checkout page accepts eCheck payments) The ID of the <input> element for the 9-digit ABA Routing Number.
bank_account_type_field_id Conditional (Use only if your checkout page accepts eCheck payments) The ID of the <select> element for the bank account type.

Note: The Library Reference must come after the mapping object in your code, but the order in which the properties are listed in the FormElementIDs object does not matter (see Example 1 for proper implementation).

 

Mapping Method - Example 1 (Credit Card & eCheck w/ separate account number inputs):

<!-- Mapping Object -->
<script>
    window.EpicTokenize = {
        FormElementIDs: {
            // The order of the following properties does not matter...
            form_id: "myForm",
            jwt_field_id: "myJWT",
            submit_button_id: "submitBtn",
            credit_card_number_field_id: "ccNumber",
            bank_account_number_field_id: "bankAccountNumber",
            routing_number_field_id: "routingNumber",
            bank_account_type_field_id: "bankType"
        }
    }
</script>

<!-- Library Reference - This MUST come after the Mapping Object (when the Mapping Method is used) -->
<script src="[path]/EpicTokenize.Min.js"></script>

...

<form id="myForm" method="post" action="...">

    <input type="hidden" id="myJWT" name="myJWT" value="{{JWT.From.Step1}}" />

    Credit Card Number: <input type="text" id="ccNumber" name="ccNumber" />

    Bank Account Number: <input type="text" id="bankAccountNumber" name="bankAccountNumber" />

    Routing Number: <input type="text" id="routingNumber" name="routingNumber" />

    Bank Account Type:
    <select id="bankType" name="bankType">
        <option value="">&nbsp;</option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>

    ...

    <button type="submit" id="submitBtn">Submit</button>

</form>

See a Live Demo of this Example

The form in the example above has separate inputs for credit card number and bank account number. If your form has a single input for both, set the values of "credit_card_number" and "bank_account_number" to the ID for that input (See Example 2).

 

Mapping Method - Example 2 (eCheck & Credit Card - Single Input):

<script>
    window.EpicTokenize = {
        FormElementIDs: {
            form_id: "myForm",
            submit_button_id: "submitButton",
            jwt_field_id: "myJWT",
            routing_number_field_id: "routingNumber",
            bank_account_type_field_id: "bankType",
            credit_card_number_field_id: "ACCOUNTNUMBER",
            bank_account_number_field_id: "ACCOUNTNUMBER"
        }
    }
</script>
<script src="[path]/EpicTokenize.Min.js"></script>
...
<form id="myForm" method="post" action="...">
    ...
    Account Number
    <input type="text" id="ACCOUNTNUMBER" />
    ...
</form>

See a Live Demo of this Example

 

If your checkout pages allow only one type of payment method, you can safely leave off fields related to the other payment method.

Mapping Method - Example 3 (CreditCard-Only):

<script>
    window.EpicTokenize = {
        FormElementIDs: {
            form_id: "myForm",
            submit_button_id: "submitButton",
            jwt_field_id: "myJWT",
            credit_card_number_field_id: "ACCOUNTNUMBER"
        }
    }
</script>
    ...
<form id="myForm" method="post" action="...">
    ...
    Account Number
    <input type="text" id="ACCOUNTNUMBER" />
    ...
</form>

 

Mapping Method - Example 4 (eCheck-Only):

<script>
    window.EpicTokenize = {
        FormElementIDs: {
            form_id: "myForm",
            submit_button_id: "submitButton",
            jwt_field_id: "myJWT",
            bank_account_number_field_id: "accountNumber",
            routing_number_field_id: "routingNumber",
            bank_account_type_field_id: "bankType"
        }
    };
</script>
<form data-epicpay-tokenize method="post" action="/APITester/ShowFormData">

    <input type="hidden" id="jwt" name="jwt" value="{{JWT.From.Step1}}" data-epicpay-jwt />
    ...
    Bank Account Number:
    <input type="text" id="bankAccountNumber" name="bankAccountNumber" data-epicpay-account_number />

    Routing Number:
    <input type="text" id="routingNumber" name="routingNumber" data-epicpay-routing_number />

    Bank Account Type:
    <select id="bankType" name="bankType" data-epicpay-bank_account_type>
        <option value=""></option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>

    <button type="submit" data-epicpay-submit>Submit</button>

</form>

 

Callback Methods

The One-Time-Tokenization Library can be configured to call two user-defined callback methods: one before tokenization occurs, and one after tokenization but prior to form submit. To configure these, assign your callback methods to the "before_tokenize_callback_function" and/or "after_tokenize_callback_function" properties of the EpicTokenize object. If you configure your form to use a callback method, it must return the JavaScript boolean value of true in order for the script to continue processing. If the first callback method returns a non-true value, tokenization will not occur. If the second callback method returns a non-true value, the form will not submit. Note: The reference to the Tokenization Library must appear after the callback methods are configured. See the examples below for proper configuration.

Using Callbacks - Data-Attributes Example:

<script>
        EpicTokenize = EpicTokenize || {};
        EpicTokenize.before_tokenize_callback_function = function(){
            alert('pre-tokenize validation done!');
            return true;
        };
        EpicTokenize.after_tokenize_callback_function = function(response) {
            if (r.status === 200) {
                var response = JSON.parse(r.response);
                if (response.status != null &&
                    response.status.response_code == 'Received' &&
                    response.result != null &&
                    response.result.token != null) {
                    alert('token: ' + response.result.token.token_number);
                }
                alert('post-tokenization validation done!');
                return true;
            };
        };
</script>

<!-- Library Reference - This MUST come after the Callback Configuration (when callbacks are used) --> 
<script src="[path]/EpicTokenize.Min.js"> </script>

<form data-epicpay-tokenize method="post" action="/APITester/ShowFormData">

    <input type="hidden" id="jwt" name="jwt" value="{{JWT.From.Step1}}" data-epicpay-jwt />
    ...
    Credit Card Number:
    <input type="text" id="creditCardNumber" name="creditCardNumber" value="" data-epicpay-credit-card-number="">

    Bank Account Number:
    <input type="text" id="bankAccountNumber" name="bankAccountNumber" value="" data-epicpay-bank-account-number="">

    Routing Number:
    <input type="text" id="routingNumber" name="routingNumber" value="" data-epicpay-routing-number="">

    Bank Account Type:
    <select id="bankType" name="bankType" data-epicpay-bank-account-type="">
        <option value=""></option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>
    <button type="submit" id="submitButton" name="submitButton" data-epicpay-submit="">Submit</button>

</form>

See a Live Demo of this Example

 

Using Callbacks - Mapped Example:

<script>
    EpicTokenize = EpicTokenize || {};
    EpicTokenize.before_tokenize_callback_function = function(){
        alert('pre-tokenize validation done!');
        return true;
    };
    EpicTokenize.after_tokenize_callback_function = function(response){  
        if (r.status === 200) {
            var response = JSON.parse(r.response);
            if (response.status != null && response.status.response_code == 'Received' && response.result != null && response.result.token != null) {
                alert('token: ' + response.result.token.token_number);
            }
            alert('post-tokenization validation done!');
            return true;
        };
    };
</script>

<script>
    window.EpicTokenize = window.EpicTokenize || {};
    window.EpicTokenize.FormElementIDs = {
        form_id: "myForm",
        jwt_field_id: "jwt",
        submit_button_id: "submitButton",
        credit_card_number_field_id: "creditCardNumber",
        bank_account_number_field_id: "bankAccountNumber",
        routing_number_field_id: "routingNumber",
        bank_account_type_field_id: "bankType"
    };
</script>

<!-- Library Reference - This MUST come after the Callback Configuration (when callbacks are used) --> 
<script src="[path]/EpicTokenize.Min.js"></script>
...
<form method="post" id="myForm" name="myForm" action="...">
    ...
    Bank Account Number:
    <input type="text" id="bankAccountNumber" name="bankAccountNumber" value="">

    Routing Number:
    <input type="text" id="routingNumber" value="" name="routingNumber">

    Bank Account Type:
    <select id="bankType" name="bankType">
        <option value=""></option>
        <option value="personal_checking">Personal Checking</option>
        <option value="business_checking">Business Checking</option>
        <option value="personal_savings">Personal Savings</option>
        <option value="business_savings">Business Savings</option>
    </select>
    ...
 </form>

See a Live Demo of this Example

 

Wallets


The EpicPay Gateway API allows merchants to store customer and account information in a secure Customer Vault. Customers stored in the Customer Vault have an associated Wallet that can hold any number of Credit Card or eCheck accounts. Each account stored in a Customer's Wallet is referred to as a "Wallet Item" and has a unique identifier called a "WalletID" that can be used to create recurring payments or place one-time transactions without sending sensitive account information each time.

Add a Wallet Item:

Adding a Wallet Item will add a new Customer record automatically unless a CustomerID is provided.

  • URL

    BaseURL/AddWalletItem

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    Conditionally Required:

    • customer_id:[String] EpicPay-defined unique identifier for a Customer (Required when adding a wallet item to an existing customer).

    • customer_address:[Object] The Customer Address Object (Not applicable when adding a wallet to an existing customer).

    • bank_account:[Object] The Bank Account Object (Required if "method" is 'echeck').

    • credit_card:[Object] The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').

    • token:[Object] The Payment Token Object (Required if "method" is 'card_token' or 'echeck_token').

    Optional:

    • client_customer_id:[String] An optional user-defined unique identifier that will be associated with the Customer.

    • billing_address:[Object] The Billing Address Object.

 

Add Wallet Request Variables


Variable Description
method String The Payment Method.
customer_id String EpicPay-defined unique identifier for a Customer (Required when adding a wallet item to an existing customer).
customer_address Object The Customer Address Object (Not applicable when adding a wallet to an existing customer).
credit_card Object The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').
bank_account Object The Bank Account Object (Required if "method" is 'echeck').
token Object The Payment Token Object (Required if "method" is 'card_token' or 'echeck_token').
client_customer_id String[40] (Optional) An optional user-defined unique identifier that will be associated with the Customer.
billing_address Object (Optional) The Billing Address Object.

 

Example Add Wallet Item Request (Credit Card)

POST {BaseURL}/addwalletitem HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"credit_card",
  "credit_card":{
    "card_number":"4111111111111111",
    "card_holder_name":"Bob Smith",
    "exp_month":"01",
    "exp_year":"2018",
    "cvv":"123"
  },
  "customer_address":{
    "first_name":"Bob",
    "last_name":"Smith",
    "company_name":"Acme Inc.",
    "address_line_1":"100 James Ave.",
    "address_line_2":"Apt 5",
    "city":"Polkton",
    "state_province":"TN",
    "postal_code":"34044",
    "country_code":"US",
    "email":"bobandmarysmith@example.com",
    "phone":{
      "number":"3235554444",
      "type":"landline" 
    }
   },
   "client_customer_id":"ABC00012"
}

 

Example Add Wallet Item Request (Card Swipe Track)

POST {BaseURL}/addwalletitem HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"card_track",
  "credit_card":{
    "card_track":"%B4111111111111111^JOHN/HENRY P          ^19012011000152002702?;4111111111111111=19012011000152002702?"
  },
  "customer_address":{
    "first_name":"John",
    "last_name":"Henry",
    "company_name":"Acme Inc.",
    "address_line_1":"200 W Main St.",
    "city":"Juarez",
    "state_province":"NM",
    "postal_code":"55044",
    "country_code":"US"
  },
  "client_customer_id":"ABC00014"
}

 

Example Add Wallet Item Request (Credit Card Token)

POST {BaseURL}/addwalletitem HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"card_token",
  "token":{
    "token_type":"epicpay",
    "token_number":"1000000404671111",
    "account_holder_name":"Donny and Jane Rogers",
    "exp_month":"01",
    "exp_year":"2018",
    "cvv":"123"
   },
  "customer_address":{
     "first_name":"Donny",
     "last_name":"Rogers",
     "company_name":"Acme Inc.",
     "address_line_1":"14 Appleton Way",
     "city":"Phoenix",
     "state_province":"AZ",
     "postal_code":"36265",
     "country_code":"US"
   },
  "client_customer_id":"ABC00022"
}

 

Example Add Wallet Item Request (eCheck)

POST {BaseURL}/addwalletitem HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"echeck",
  "bank_account":{
   "account_type":"personal_checking",
   "routing_number":"211370545",
   "account_number":"01234567890123",
   "account_holder_name":"Mike Dole"
  },
  "customer_address":{
    "first_name":"Mary",
    "last_name":"Dole",
    "company_name":"Acme Inc.",
    "address_line_1":"1223 W Melinda St.",
    "address_line_2":"Suite 400",
    "city":"Topeka",
    "state_province":"KS",
    "postal_code":"29232",
    "country_code":"US"
   },
  "client_customer_id":"ABC00029"
}

 

Example Add Wallet Item Request (eCheck Token)

POST {BaseURL}/addwalletitem HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"echeck_token",
  "token":{
    "token_type":"epicpay",
    "token_number":"10000004504500123",
    "account_holder_name":"Ted Banner"
  },
  "customer_address":{
    "first_name":"Ted",
    "last_name":"Banner",
    "company_name":"Acme Inc.",
    "address_line_1":"49433 Franklin St.",
    "address_line_2":"Apt 9",
    "city":"Brooklyn",
    "state_province":"NY",
    "postal_code":"77455",
    "country_code":"US"
  },
  "client_customer_id":"ABC00042"
}

 

Example Add Wallet Item Request (Adding to an Existing Customer)

POST {BaseURL}/addwalletitem HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "method":"credit_card",
  "customer_id":"12E4B05BBD624B0AB5A5177A8192DB70",
  "credit_card":{
    "card_number":"4111111111111111",
    "card_holder_name":"Bob Smith",
    "exp_month":"01",
    "exp_year":"2018",
    "cvv":"123"
  }
}

 

Edit a Wallet Item:

Wallet Items stored on the EpicPay Gateway can be modified, but only a select subset of the properties can be updated. Properties associated with the Customer, such as "customer_address" and "client_customer_id" can be changed using the EditCustomer API Method. If you need to make changes to any other non-updatable properties, such as the account number, routing number, or the cvv code, you will need to create a new Wallet Item. All requests to edit a Wallet Item must include the WalletID as part of the URL. In the body of the request, provide all properties which should have values, not only the properties to be changed (Any null or empty values in the request will be saved). See the table below for a list of which properties of the Wallet Item are updatable.

Wallet Item Type Updatable Properties
eCheck "account_holder_name"
Credit Card "account_holder_name", "exp_month", "exp_year", "billing_address"
  • URL

    BaseURL/EditWalletItem/WalletID

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    • account_holder_name:[String] Account holder's name as it appears on the Credit Card or Bank Account.

    Conditionally Required:

    • exp_month:[String (2-digit: "01" - "12")] Expiration Month expressed as a two-digit number (Required if the wallet item is a credit card).

    • exp_year:[String (4-digit)] Expiration Year expressed as a four-digit number (Required if the wallet item is a credit card).

    Optional:

Edit Wallet Request Variables


Variable Description
account_holder_name String[50] Account holder's name as it appears on the Credit Card or Bank Account.
exp_month String[2] Expiration Month expressed as a two-digit number (Required if the wallet item is a credit card).
exp_year String[4] Expiration Year expressed as a four-digit number (Required if the wallet item is a credit card).
billing_address Object (Optional) The Billing Address Object.
WalletID String The unique identifier for the Wallet Item to be modified. (This identifier is required in order to edit a wallet).

 

Example Edit Wallet Item Request (eCheck)

POST {BaseURL}/editwalletitem/34f94d453fd749ffb8eb9652c4d65a41 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "account_holder_name":"Bob and Mary Smith"
}

 

Example Edit Wallet Item Request (Credit Card)

POST {BaseURL}/editwalletitem/81939d158a6a428084dfc698f6778af5 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "account_holder_name":"John Thomas",
  "exp_month":"10",
  "exp_year":"2022",
  "billing_address":{
    "first_name":"Bob",
    "last_name":"Smith",
    "address_line_1":"100 James Ave.",
    "address_line_2":"Apt 5",
    "city":"Polkton",
    "state_province":"TN",
    "postal_code":"34044",
    "country_code":"US",
    "email":"bobandmarysmith@example.com",
    "phone":{
      "number":"3235554444",  
      "type":"landline" 
    }
  }
}

Delete a Wallet Item:

Wallet Items can be deleted via the EpicPay Gateway API. All requests to delete a Wallet Item must include the WalletID as part of the URL.

 

Delete Wallet Request Variables


Variable Description
WalletID String The unique identifier for the Wallet Item to be deleted.

Example Delete Wallet Request

POST {BaseURL}/deletewalletitem/CB668C03E0B84C5E982DDFA19519A109 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

 

Example Delete Wallet Curl

curl {BaseURL}/deletewalletitem/CB668C03E0B84C5E982DDFA19519A109
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

Wallet Response

All AddWallet and EditWallet requests will return the same response object. Requests to DeleteWallet will only return only the Status object.

 

Wallet Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   wallet Object
   client_customer_id String An user-defined unique identifier that will be associated with the Customer.
   customer_id String EpicPay-defined identifier for the Customer associated with the Wallet. (This identifier is required in order to add another wallet item to the same customer).
   wallet_id String EpicPay-defined unique identifier for the Wallet. (This identifier is required in order to modify or delete an existing wallet item. It can also be used to place Transactions).

 

Example Add Wallet Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  },
  "result": {
    "wallet": {
      "client_customer_id": null,
      "customer_id": "f92d62597c50401c960523bf6b0226f4",
      "wallet_id": "fc9416714c8c4746b50de05ccc7eee16"
    }
  }
}

 

Example Edit Wallet Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  },
  "result": {
    "wallet": {
      "client_customer_id": "",
      "customer_id": "f92d62597c50401c960523bf6b0226f4",
      "wallet_id": "fc9416714c8c4746b50de05ccc7eee16"
    }
  }
}

 

Example Delete Wallet Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Edit a Customer:

Use this method to change the "customer_address" or "client_customer_id" associated with a Customer. All requests to edit a Customer must include the CustomerID as part of the URL. In the body of the request, provide all properties which should have values, not only the properties to be changed (Any null or empty values in the request will be saved).

  • URL

    BaseURL/EditCustomer/CustomerID

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • customer_address:[Object] The Customer Address Object ("first_name" and "last_name" are required as part of this object).

    Optional:

    • client_customer_id:[String] An optional user-defined unique identifier associated with the Customer.

 

Edit Customer Request Variables


Variable Description
customer_address Object The Customer Address Object ("first_name" and "last_name" are required as part of this object).
client_customer_id String (Optional) A user-defined unique identifier associated with the Customer.
CustomerID String EpicPay-defined unique identifier for the Customer. (This identifier is required in order to edit a Customer).

 

Example Edit Customer Request

POST {BaseURL}/editcustomer/9b975f0a04f34af59a6e79f7d0144784 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "client_customer_id":"ABX12033",
  "customer_address":{
    "first_name":"Bobby",
    "last_name":"Shmidt",
    "address_line_1":"1223 W Colander St.",
    "address_line_2":"Suite 400",
    "city":"Topeka",
    "state_province":"KS",
    "postal_code":"29232",
    "country_code":"US",
    "company":"123",
    "email":"abc@example.com",
    "phone":{
      "number":"3335554444",
      "type":"mobile"
    }
  }
}

 

Customer Response

 

Customer Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes).
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   customer Object
     customer_address String Customer Address.
     customer_id String EpicPay-defined unique identifier for the Customer. (Returned unmodified).

 

Example Edit Customer Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "result": {
    "customer": {
      "client_customer_id": "ABX12033",
      "customer_address": {
        "first_name": "Bobby",
        "last_name": "Shmidt",
        "company_name": null,
        "address_line_1":"1223 W Colander St.",
        "address_line_2":"Suite 400",
        "city": "Topeka",
        "state_province": "KS",
        "postal_code": "29232",
        "country_code": "US",
        "email": "abc@example.com",
        "phone": {
          "number": "3335554444",
          "type": "mobile"
        }
      },
      "customer_id": "9b975f0a04f34af59a6e79f7d0144784"
      }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Recurring Billing


The EpicPay Gateway API allows you to set up Recurring Billing with a great amount of flexibility. Subscriptions can have a payment frequency of "Every n days", "Every n weeks", "Every n months", or "Twice a month". When creating a recurring billing subscription, you may choose to continue billing until cancelled, or expire the subscription after a date is reached or a specified number of payments have been made. Subscriptions which expire can be configured with a different Last Payment Amount. You may also configure the subscription to send notification emails to customers after each payment is made. See the table below for more information about payment frequency.

Frequency Other Required Properties Example Usage
"every_n_days" You must set "period" - the number of days between payments. To charge every 3 days, set period to 3.
"every_n_weeks" You must set "period" - the number of weeks between payments. To charge every-other Monday, set period to 2 and choose a "next_payment_date" that falls on a Monday.
"every_n_months" You must set "period" - the number of months between payments. To charge on the 10th of every month, set period to 1 and choose a "next_payment_date" that falls on the 10th of a month.
"twice_every_month" You must set "date_of_month_1", "date_of_month_2"- the two payment days of each month. You must choose a "next_payment_date" that falls on either "date_of_month_1" or "date_of_month_2". To bill each month on the 1st and 15th, set "date_of_month_1" to 1 and set "date_of_month_2" to 15. Choose a "next_payment_date" that falls on the 1st or 15th of the month.

Add a Subscription:

Use this method to put a customer on a recurring billing plan.

  • URL

BaseURL/AddSubscription

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • amount:[Integer] Transaction amount in cents.

    • currency:[String] Three-letter ISO currency code representing the currency in which the payment was made.

    • method:[String] A payment method to use for the recurring payment. If a wallet item is used, it must belong to the merchant.

    • next_payment_date:[Date (YYYY-MM-DD)] The date in which recurring payments will begin.

    • frequency:[String] Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_days', 'every_n_weeks', 'every_n_months', or 'twice_every_month').

    Conditionally Required:

    • period:[Integer (range: 1-90)] The number of days, weeks, or months between payments. (This is valid and required if "frequency" is 'every_n_days', 'every_n_weeks', or 'every_n_months').

    • date_of_month_1:[Integer (range: 1-31)] The first payment day of each month (This is valid and required if "frequency" is 'twice_every_month').

    • date_of_month_2:[Integer (range: 1-31)] The second payment day of each month (This is valid and required if "frequency" is 'twice_every_month').

    • credit_card:[Object] The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').

    • bank_account:[Object] The Bank Account Object (Required if "method" is 'echeck').

    • token:[Object] The Payment Token Object (Required if "method" is 'echeck_token' or 'card_token').

    • wallet:[Object] The Wallet Object (Required if "method" is 'wallet').

    • customer_address:[Object] The Customer Address Object (Only applicable when "method" is not 'wallet').

    • sec_code:[String (3)] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions (Required if "method" is 'echeck').

    Optional:

    • secondary_amount:[Integer] Secondary transaction amount in cents.

    • alert_after:[Boolean] Whether to send a notification after each payment is made. Emails will be sent to the email address you provided in the "customer_address" object. (Values: 'true', 'false'; Default: 'false').

    • client_order_id:[String] An optional user-defined unique identifier that will be associated with the Subscription. Format: [A-Za-z0-9-#]{0,40}._

    • client_customer_id:[String] An optional user-defined unique identifier that will be associated with the Customer. Format: [A-Za-z0-9-#]{0,40}._

    • total_payments:[Integer] An optional number of payments to make before the subscription expires. (If you omit "total_payments" and "last_payment_date", the subscription will not expire.)

    • last_payment_date:[Date (YYYY-MM-DD)] An optional date on which the subscription will expire. (If you omit "total_payments" and "last_payment_date", the subscription will not expire.)

    • last_amount:[Integer] An optional amount in cents to charge for the last payment instead of "amount". (This is only valid if "total_payments" or "last_payment_date" are set).

    • billing_address:[Object] The Billing Address Object.

    • entry_description:[String] A description of the purpose of the ACH transaction. This will appear on the consumer’s bank account statement (Applicable only when “method” is 'echeck', 'echeck_token' or 'wallet' of type eCheck).

 

Add Subscription Request Variables


Variable Description
method String A payment method to use for the recurring payment.
currency String Three-letter ISO currency code representing the currency in which the payment was made.
amount Integer Transaction amount in cents.
secondary_amount Integer Secondary transaction amount in cents.
last_amount Integer (Optional) The amount in cents to charge for the last payment instead of "amount". (This is only valid if 'total_payments' or 'last_payment_date' are set).
last_secondary_amount Integer (Optional) The secondary amount in cents to charge for the last payment instead of "secondary_amount". (This is only valid if 'total_payments' or 'last_payment_date' are set).
next_payment_date Date [YYYY-MM-DD] The date in which recurring payments will begin.
frequency String Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_days', 'every_n_weeks', 'every_n_months', or 'twice_every_month').
period Integer [range: 1-90] The number of days, weeks, or months between payments. (This is valid and required if "frequency" is 'every_n_days', 'every_n_weeks', or 'every_n_months').
date_of_month_1 Integer [range: 1-31] The first payment day of each month (This is valid and required if "frequency" is 'twice_every_month').
date_of_month_2 Integer [range: 1-31] The second payment day of each month (This is valid and required if "frequency"" is 'twice_every_month').
credit_card Object The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').
bank_account Object The Bank Account Object (Required if "method" is 'echeck').
token Object The Payment Token Object (Required if "method" is 'echeck_token' or 'card_token').
wallet Object The Wallet Object (Required if "method" is 'wallet').
customer_address Object The Customer Address Object (Only applicable when "method" is not 'wallet').
alert_after Boolean (Optional) Whether to send a notification after each payment is made. Emails will be sent to the email address you provided in the "customer_address" object. (Values: 'true', 'false'; Default: 'false').
client_order_id String (Optional) A user-defined value that will be the unique identifier for this Subscription. Format: [A-Za-z0-9-_#]{0,40}.
client_customer_id String (Optional) A user-defined value that will be the unique identifier for the Customer. Format: [A-Za-z0-9-_#]{0,40}.
total_payments Integer (Optional) The number of payments to make before the subscription expires. (If you omit "total_payments" and "last_payment_date", the subscription will not expire).
last_payment_date Date [YYYY-MM-DD] (Optional) The date on which the subscription will expire. (If you omit "total_payments" and "last_payment_date", the subscription will not expire).
billing_address Object (Optional) The Billing Address Object.
sec_code String[3] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions. (Required when "method" is 'echeck').
entry_description String A description of the purpose of the ACH transaction. This will appear on the consumer’s bank account statement (Applicable only when "method" is 'echeck', 'echeck_token' or 'wallet' of type eCheck).

 

Example Add Subscription Request (Every 2 Weeks, Never Expires, using New Customer and New Credit Card)

POST {BaseURL}/addsubscription HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "client_order_id": "bshjgh1234543",
  "currency": "usd",
  "amount": 220,
  "frequency": "every_n_weeks",
  "period": 2,
  "next_payment_date": "2017-12-03",
  "alert_after": true,
  "method": "credit_card",
  "credit_card": {
    "card_holder_name": "Bob Smith",
    "card_number": "4111111111111111",
    "cvv": "349",
    "exp_month": "01",
    "exp_year": "19"
  },
  "client_customer_id": "yiuLpoWAA65434",
  "customer_address": {
    "address_line_1": "201 Ever Ln.",
    "address_line_2": "Suite 201",
    "city": "Overland",
    "company_name": "Texas Lone Star",
    "country_code": "US",
    "email": "bsmith@epicpay.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "postal_code": "66023-3747",
    "state_province": "KS",
    "phone": {
      "number": "2014791255",
      "type": "mobile"
    }
  },
  "billing_address": {
    "address_line_1": "201 Ever Ln.",
    "address_line_2": "Suite 201",
    "city": "Overland",
    "company_name": "Texas Lone Star",
    "country_code": "US",
    "email": "bsmith@epicpay.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "postal_code": "66023-3747",
    "state_province": "KS",
    "phone": {
      "number": "2014791255",
      "type": "mobile"
    }
  }
}

 

Example Add Subscription Request (Every Month, Expires on Date, has Secondary Amounts, using Existing Customer Wallet)

POST {BaseURL}/addsubscription HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "client_order_id": "ABC10002",
  "currency": "usd",
  "amount": "1250",
  "secondary_amount": 20,
  "last_payment_date": "2023-12-25",
  "last_amount": 500,
  "last_secondary_amount": 50,
  "frequency": "every_n_months",
  "period": "1",
  "next_payment_date": "2018-04-25",
  "alert_after": true,
  "method": "wallet",
  "wallet":{
    "wallet_id": "05DAD3C3C3D0464697D136D7D8D5BAD8",
    "cvv": "123"
  }
}

 

Example Add Subscription Request (Twice Every Month, Expires after 12 Payments, using New Customer and eCheck)

POST {BaseURL}/addsubscription HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
    "amount": 120,
    "currency": "usd",
    "method":"echeck",
    "frequency": "twice_every_month",
    "date_of_month_1": "1",
    "date_of_month_2": "15",
    "next_payment_date": "2019-07-04",
    "total_payments": "12",
    "alert_after": "true",
    "bank_account"{
        "account_type": "personal_checking",
        "routing_number": "111000025",
        "account_number": "87654321",
        "account_holder_name": "John Doe"
    },
    "sec_code": CCD,
    "entry_description": "Payment",
    "customer_address": {
        "address_line_1": "201 Ever Ln.",
        "address_line_2": "Suite 201",
        "city": "Overland",
        "company_name": "Texas Lone Star",
        "country_code": "US",
        "email": "bsmith@epicpay.com",
        "first_name": "Bob",
        "last_name": "Smith",
        "postal_code": "66023-3747",
        "state_province": "KS",
        "phone": {
          "number": "2014791255",
          "type": "mobile"
        }
    }
}

 

Edit a Subscription:

Recurring Billing Subscriptions can be modified, but only a select subset of the properties can be updated. To make changes to the Customer or Wallet associated with a Subscription, use the EditWalletItem or EditCustomer API Methods. All requests to edit a Subscription must include the SubscriptionID as part of the URL. In the body of the request, provide all properties which should have values, not only the properties to be changed. Any omitted or empty properties in the request will overwrite existing values.

  • URL

BaseURL/EditSubscription/SubscriptionID

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • SubscriptionID: String The unique identifier for the subscription. This value must be provided as part of the URL.

    • method:[String] A payment method to use for the recurring payment. If a wallet item is used, it must belong to the merchant.

    • credit_card:[Object] The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').

    • bank_account:[Object] The Bank Account Object (Required if "method" is 'echeck').

    • token:[Object] The Payment Token Object (Required if "method" is 'echeck_token' or 'card_token').

    • wallet:[Object] The Wallet Object (Required if "method" is 'wallet').

    • customer_address:[Object*] The Customer Address Object (Only applicable when "method" is not 'wallet').

    • alert_after:[Boolean] Whether to send a notification after each payment is made. Emails will be sent to the email address you provided in the "customer_address" object. (Values: 'true', 'false'; Default: 'false').

    • client_customer_id:[String] An optional user-defined unique identifier that will be associated with the Customer. Format: [A-Za-z0-9-#]{0,40}._

    • amount:[Integer] Transaction amount in cents.

    • currency:[String] Three-letter ISO currency code representing the currency in which the payment was made.

    • next_payment_date:[Date (YYYY-MM-DD)] The date in which recurring payments will begin.

    • frequency:[String] Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_days', 'every_n_weeks', 'every_n_months', or 'twice_every_month').

    • period:[Integer (range: 1-90)] The number of days, weeks, or months between payments. (This is valid and required if "frequency" is 'every_n_days', 'every_n_weeks', or 'every_n_months').

    • date_of_month_1:[Integer (range: 1-31)] The first payment day of each month (This is valid and required if "frequency" is 'twice_every_month').

    • date_of_month_2:[Integer (range: 1-31)] The second payment day of each month (This is valid and required if "frequency" is 'twice_every_month').

    • client_order_id:[String] An optional user-defined unique identifier that will be associated with the Subscription. Format: [A-Za-z0-9-#]{0,40}._

    • total_payments:[Integer] An optional number of payments to make before the subscription expires. (If you omit "total_payments" and "last_payment_date", the subscription will not expire.)

    • last_payment_date:[Date (YYYY-MM-DD)] An optional date in which the subscription will expire. (If you omit "total_payments" and "last_payment_date", the subscription will not expire.)

    • secondary_amount:[Integer] Secondary transaction amount in cents.

    • last_amount:[Integer] An optional amount in cents to charge for the last payment instead of "amount" (This is only valid if "total_payments" or "last_payment_date" are set).

    • last_secondary_amount:[Integer] An optional secondary amount in cents for the last payment instead of "secondary_amount" (This is only valid if "total_payments" or "last_payment_date" are set).

    • billing_address:[Object] The Billing Address Object An optional billing address information for the Wallet Item.

    • sec_code:[String (3)] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions (Required if "method" is 'echeck').

    • entry_description:[String] A description of the purpose of the ACH transaction. This will appear on the consumer’s bank account statement (Applicable only when “method” is 'echeck', 'echeck_token' or 'wallet' of type eCheck).

 

Edit Subscription Request Variables


Variable Description
SubscriptionID String The unique identifier for the Subscription to be modified. This value must be provided as part of the URL.
method String A payment method to use for the recurring payment.
currency String Three-letter ISO currency code representing the currency in which the payment was made.
amount Integer Transaction amount in cents.
secondary_amount Integer Secondary transaction amount in cents.
last_amount Integer (Optional) The amount in cents to charge for the last payment instead of "amount". (This is only valid if "total_payments" or "last_payment_date" are set).
last_secondary_amount Integer (Optional) The secondary amount in cents to charge for the last payment instead of "secondary_amount". (This is only valid if 'total_payments' or 'last_payment_date' are set).
next_payment_date Date [YYYY-MM-DD] The date in which recurring payments will begin.
frequency String Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_day', 'every_n_weeks', 'every_n_months', or 'twice_every_month').
period Integer The number of days, weeks, or months between payments. (This is valid and required if "frequency" is 'every_n_days', 'every_n_weeks', or 'every_n_months').
date_of_month_1 Integer The first payment day of each month (This is valid and required if "frequency" is 'twice_every_month').
date_of_month_2 Integer The second payment day of each month (This is valid and required if "frequency" is 'twice_every_month').
credit_card Object The Credit Card Object (Required if "method" is 'credit_card' or 'card_track').
bank_account Object The Bank Account Object (Required if "method" is 'echeck').
token Object The Payment Token Object (Required if "method" is 'echeck_token' or 'card_token').
wallet Object The Wallet Object (Required if "method" is 'wallet').
customer_address Object The Customer Address Object (Only applicable when "method" is not 'wallet').
alert_after Boolean (Optional) Whether to send a notification after each payment is made. Emails will be sent to the email address you provided in the "customer_address" object. (Values: 'true', 'false'; Default: 'false').
client_order_id String (Optional) A user-defined value that will be the unique identifier for this Subscription. Format: [A-Za-z0-9-_#]{0,40}.
client_customer_id String (Optional) A user-defined value that will be the unique identifier for the Customer. Format: [A-Za-z0-9-_#]{0,40}.
total_payments Integer (Optional) The number of payments to make before the subscription expires. (If you omit "total_payments" and "last_payment_date", the subscription will not expire).
last_payment_date Date [YYYY-MM-DD] (Optional) The date on which the subscription will expire. (If you omit "total_payments" and "last_payment_date", the subscription will not expire).
billing_address Object (Optional) The Billing Address Object.
sec_code String[3] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions. (Required when "method" is 'echeck').
entry_description String A description of the purpose of the ACH transaction. This will appear on the consumer’s bank account statement (Applicable only when "method" is 'echeck', 'echeck_token' or 'wallet' of type eCheck).

 

Example Edit Subscription Request (Use a Different Wallet Item / Same Customer)

POST {BaseURL}/editsubscription/2600612EB2874574AFA8F7AE7723C762 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "client_order_id": "ABC10002",
  "currency": "usd",
  "amount": 1250,
  "total_payments": 10,
  "last_amount": 500,
  "next_payment_date": "2018-04-25",
  "frequency": "every_n_months",
  "period": "3",
  "last_payment_date": "2023-12-25",
  "alert_after": true,
  "method": "wallet",
  "wallet":{
    "wallet_id": "05DAD3C3C3D0464697D136D7D8D5BAD8",
    "cvv": "123"
  }
}

 

Example Edit Subscription Request (Use New Credit Card / New Customer)

POST {BaseURL}/editsubscription/2600612EB2874574AFA8F7AE7723C762 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "client_order_id": "bshjgh1234543",
  "currency": "usd",
  "amount": 220,
  "secondary_amount": 20,
  "last_payment_date": "2018-08-15",
  "last_amount": 500,
  "last_secondary_amount": 50,
  "frequency": "every_n_weeks",
  "next_payment_date": "2017-12-03",
  "period": 2,
  "alert_after": true,
  "method": "credit_card",
  "credit_card": {
    "card_holder_name": "Bob Smith",
    "card_number": "4111111111111111",
    "cvv": "349",
    "exp_month": "01",
    "exp_year": "19"
  },
  "billing_address": {
    "address_line_1": "201 Ever Ln.",
    "address_line_2": "Suite 201",
    "city": "Overland",
    "company_name": "Texas Lone Star",
    "country_code": "US",
    "email": "DaffySnow@epicpay.com",
    "first_name": "Daffy",
    "last_name": "Snow",
    "phone": {
      "number": "2014791255",
      "type": "mobile"
    },
    "postal_code": "66023-3747",
    "state_province": "KS"
  },
  "client_customer_id": "yiuLpoWAA65434",
  "customer_address": {
    "address_line_1": "201 Ever Ln.",
    "address_line_2": "Suite 201",
    "city": "Overland",
    "company_name": "Texas Lone Star",
    "country_code": "US",
    "email": "bsmith@epicpay.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "phone": {
      "number": "2014791255",
      "type": "mobile"
    },
    "postal_code": "66023-3747",
    "state_province": "KS"
  }
}

 

Example Edit Subscription Curl

curl {BaseURL}/editsubscription
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "client_order_id":"ABC10044",
      "amount":"1000",
      "currency":"usd",
      "next_payment_date":"2018-05-25",
      "frequency":"every_n_weeks",
      "period":"2",
      "wallet":"{
        \"wallet_id\":\"8699D51F4DD4476E90614797F78FAD35\"
     }"
   }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

Suspend a Subscription:

Recurring Billing Subscriptions can be "suspended", an action that makes a subscription inactive. All requests to suspend a subscription must include the SubscriptionID as part of the URL.

  • URL

    BaseURL/Subscription/Suspend/SubscriptionID

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • SubscriptionID:[String] The unique identifier for the subscription. This value must be provided as part of the URL.

 

Suspend Subscription Request Variables


Variable Description
SubscriptionID String The unique identifier for the subscription. This value must be provided as part of the URL.

 

Suspend Subscription Response Variables


Variable Description
subscription Object The subscription status change object.
    id String The unique identifier of the modified subscription.
    status String The new status of the subscription.

 

Example Suspend Subscription Request

POST {BaseURL}/subscription/suspend/ADD48D8E2F21477CA89E023A6DFD472A HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

 

Example Suspend Subscription Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 450

{
  "result": {
    "subscription": {
      "id": "ADD48D8E-2F21-477C-A89E-023A6DFD472A",
      "status": "Suspended"
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

 

Example Suspend Subscription Curl

curl {BaseURL}/subscription/suspend/ADD48D8E2F21477CA89E023A6DFD472A
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"

Unsuspend a Subscription:

Recurring Billing Subscriptions can be "unsuspended", an action that removes "suspended" status from a subscription. All requests to unsuspend a subscription must include the SubscriptionID as part of the URL.

  • URL

    BaseURL/Subscription/Unsuspend/SubscriptionID

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • SubscriptionID:[String] The unique identifier for the subscription. This value must be provided as part of the URL.

 

Unsuspend Subscription Request Variables


Variable Description
SubscriptionID String The unique identifier for the subscription. This value must be provided as part of the URL.

 

Suspend Subscription Response Variables


Variable Description
subscription Object The subscription status change object.
    id String The unique identifier of the modified subscription.
    status String The new status of the subscription.

 

Example Unsuspend Subscription Request

POST {BaseURL}/subscription/unsuspend/ADD48D8E2F21477CA89E023A6DFD472A HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

 

Example Unsuspend Subscription Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 450

{
  "result": {
    "subscription": {
      "id": "ADD48D8E-2F21-477C-A89E-023A6DFD472A",
      "status": "Unsuspended"
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

 

Example Unsuspend Subscription Curl

curl {BaseURL}/subscription/unsuspend/ADD48D8E2F21477CA89E023A6DFD472A
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"

Delete a Subscription:

Recurring Billing Subscriptions can be deleted via the EpicPay Gateway API. All requests to delete a Subscription must include the SubscriptionID as part of the URL.

  • URL

    BaseURL/DeleteSubscription/SubscriptionID

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json  

Delete Subscription Request Variables


Variable Description
SubscriptionID String The unique identifier for the Subscription to be deleted.

 

Example Delete Subscription Request

POST {BaseURL}/deletesubscription/86D7D5D4A35D49F0BF7720613DE7EF43 HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

 

Example Delete Subscription Curl

curl {BaseURL}/deletesubscription/86D7D5D4A35D49F0BF7720613DE7EF43
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

Subscription Response

 

Subscription Response Variables


Variable Description
status Object Status of the API Request.
  response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
  reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
  reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
  subscription Object
    customer_id String EpicPay-defined unique identifier for a Customer.
    wallet_id String EpicPay-defined unique identifier for the Wallet.
    subscription_id String EpicPay-defined unique identifier for the Subscriptions (This identifier is required in order to modify or delete an existing subscription).
    amount Integer Transaction amount.
    last_amount Integer The optional amount to charge for the last payment instead of "amount" (Returned unmodified).
    currency String Three-letter ISO currency code representing the currency in which the payment was made (Returned unmodified).
    frequency String Whether to charge on a daily, weekly, monthly, or bi-monthly basis (Returned unmodified).
    period Integer The number of days, weeks, or months between payments. (Returned unmodified).
    date_of_month_1 Integer The first payment day of each month (Returned unmodified).
    date_of_month_2 Integer The second payment day of each month (Returned unmodified).
    next_payment_date Date [YYYY-MM-DD] The date in which recurring payments will begin (Returned unmodified).
    last_payment_date Date [YYYY-MM-DD] The date on which the subscription will expire (Returned unmodified).
    total_payments Integer The number of payments to make before the subscription expires (Returned unmodified).
    client_order_id String The optional user-defined unique identifier that will be associated with the Subscription (Returned unmodified).
    client_customer_id String The optional user-defined unique identifier that will be associated with the Customer (Returned unmodified).
    alert_after Boolean Whether to send a notification after each payment is made. Emails will be sent to the email address you provided in the "customer_address" object. (Values: 'true', 'false'; Default: 'false').
    sec_code String[3] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions.
    entry_description String A description of the purpose of the ACH transaction. This will appear on the consumer’s bank account statement.

Example Add Subscription Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "result": {
    "subscription": {
      "customer_id": "762b9ebf3e404a10ab8048c52a05033f",
      "wallet_id": "23c1ad84544c4275b7ad002e15639683",
      "subscription_id": "2600612EB2874574AFA8F7AE7723C762",
      "amount": 220,
      "last_amount": 500,
      "currency": "usd",
      "frequency": "every_n_weeks",
      "period": 2,
      "date_of_month_1": 0,
      "date_of_month_2": 0,
      "next_payment_date": "2017-10-23",
      "last_payment_date": "2018-08-15",
      "total_payments": 3,
      "client_order_id": "bshjgh1234543",
      "client_customer_id": "yiuLpoWAA65434",
      "alert_after": true,
      "sec_code": "CCD",
      "entry_description": "Payment"
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

 

Example Edit Subscription Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "result": {
    "subscription": {
      "customer_id": "0c332c84d47d4a39bd9404938abc6a62",
      "wallet_id": "37da26738eb94895b0cffd3a4c1b25a4",
      "subscription_id": "2600612EB2874574AFA8F7AE7723C762",
      "amount": 220,
      "last_amount": 500,
      "currency": "usd",
      "frequency": "every_n_weeks",
      "period": 2,
      "date_of_month_1": 0,
      "date_of_month_2": 0,
      "next_payment_date": "2017-12-03",
      "last_payment_date": "2018-08-15",
      "total_payments": 3,
      "client_order_id": "bshjgh1234543",
      "client_customer_id": "yiuLpoWAA65434",
      "alert_after": true,
      "sec_code": "CCD",
      "entry_description": "Payment"
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

 

Example Delete Subscription Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Get Transaction:

Returns information about a previous transaction. This request must include (as part of the URL) the "transaction_id" or "client_transaction_id" associated with a transaction. See the table below for more information.

  • URL

    BaseURL/GetTransaction/id

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • id_source:[String] The type of identifier you are providing in the URL (Values: 'epicpay' or 'client'). Format for Client Transaction ID: [A-Za-z0-9-]{0,40}. Format for Client Order ID: [A-Za-z0-9-#]{0,40}. _

 

Get Transaction Request Variables


Variable Description
id_source String The type of transaction source. Values: 'epicpay', 'client'
id String The "transaction_id" or "client_transaction_id" associated with a transaction. This parameter must be included as part of the URL. If you choose to supply the "transaction_id", you must specify "id_source":"epicpay" in the request body. If you instead provide a "client_transaction_id", you must specify "id_source":"client" in the body of the request. Format for Client Transaction ID: [A-Za-z0-9-]{0,40}. Format for Client Order ID: [A-Za-z0-9-_#]{0,40}.

 

Example Request

POST {BaseURL}/GetTransaction/29048
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "id_source":"client"
}

 

Example Curl

curl {BaseURL}/GetTransaction/29048
-X POST
-u API Key ID:Password
-H "Content-Type: application/json"
-d '{ "id_source":"epicpay" }'

Note: Single quotes are not supported in Windows Curl. Escape inside quotes with backslash. e.g.: -d "{\"KEY\":\"VALUE\"}"

Get Transaction Response

 

Get Transaction Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   payment Object
     transaction_id String[40] A unique identifier to associate with a payment request. This id is required to modify (i.e. 'capture', 'void', or 'credit') the payment later.
     authorization_number String Authorization number returned by the cardholder's financial institution when a transaction has been approved.
     avs_code String Result code for Address Verification(AVS).
     cvv_code String Result code for CVV Authentication (Returned from the bank - will be blank if CVV is not supported.)
     transaction_type String The type of transaction performed (Returned unmodified).
     amount Integer Payment amount in cents (Returned unmodified).
     currency String[3] Three-letter ISO currency code representing the currency in which the payment was made (Returned unmodified).
     client_transaction_id String[40] A client-defined value that can be used to internally identify the transaction (Returned unmodified).
     method String The payment method (Returned unmodified).
     credit_card Object The Credit Card Object along with the card_type. (Returned with sensitive fields removed or masked).
     bank_account Object The Bank Account Object (Returned with sensitive fields removed or masked).
     wallet Object The Wallet Object (Returned with sensitive fields removed or masked).
     token Object The Payment Token Object (Returned with sensitive fields removed or masked).
     billing_address Object The Billing Address Object (Returned unmodified).
     metadata Object A collection of additional properties. See Metadata Properties for more information.
     sec_code String[3] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions.
     entry_description String A description of the purpose of the ACH transaction.

 

Example Get Transaction Response (epicpay)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 550

{
  "result": {
    "payment": {
      "transaction_type": "Sale",
      "amount": 111,
      "currency": "USD",
      "client_transaction_id": "AXB1233309",
      "transaction_id": "39420",
      "method": "Visa",
      "sec_code": "WEB",
      "entry_description": "ECToken",
      "authorization_number": "TEST",
      "avs_code": "Y",
      "cvv_code": "M",
      "credit_card": {
        "card_type": "visa",
        "card_number": "****1111",
        "card_holder_name": "Bob Smith"
      },
      "billing_address": {
        "first_name": "Johnny",
        "last_name": "Bravo",
        "company_name": "Bravo Industries",
        "address_line_1": "245 Main St.",
        "address_line_2": "Suite 101",
        "city": "Templeton",
        "state_province": "VA",
        "country_code": "US",
        "postal_code": "01803-3747",
        "email": "example@example.com",
        "phone": {
          "number": "555-555-1212",
          "type": "Mobile"
        }
      }
      "metadata": {
        "key1": "value1",
        "key2": "value2",
        ...
      }
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Event Management


EpicPay's Event Management feature allows merchants and partners to receive notifications anytime a specific event occurs at EpicPay. For example, you may use this feature to receive a Webhook Callback whenever a payment is attempted. To receive notifications, you must create an Event Subscription. When you create an Event Subscription, you will specify the type of Event for which you want to be notified, the notification type (email or webhook), as well as the recipient address. Please contact your Account Manager if you wish to configure an Event Subscription.

Webhooks

 

Introduction


EpicPay merchants can opt to receive a webhook callback each time a payment is made, for both single payments and the payments created due to a Recurring Payment Plan. The format of the webhook is JSON. NOTE: Please insure that your endpoint(s) can receive communication from the following IP addresses: 52.0.151.12, 34.206.191.222.

 

Configuration


Webhooks will only be sent over HTTPS (TLS 1.2), so you must configure your endpoint to receive requests using TLS version 1.2. Optionally, you may secure your endpoint with Basic Authentication. If you do, we will send the username and password that you provide us with each callback.

For more information on Basic Authentication, see: Wikipedia: Basic Access Authentication.

For more on TLS, see: Wikipedia: Transport Layer Security.

There are two options for configuring webhooks:

  1. To configure a single endpoint for all payments (and optionally provide us with your Basic Authentication credentials), contact your Account Manager.
  2. If you are using direct API integration, you can provide a callback endpoint with each payment request using the “callback_url” property (see the example request below). Note: this option does not allow the use of Basic Authentication.

After completing your webhook endpoint, you can test it here.

 

Example Payment Request with Callback Url

POST {BaseURL}/authorize HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0MzpnZCaGfFZCaGpnZCfF0Mzpn3F0Mzpn3DF
Content-Type: application/json

{
  "amount":"111",
  "currency":"usd",
  "method":"credit_card",
  "callback_url":"https://www.example.com",
  "transaction_type":"authorize",
  "credit_card":{
    "card_number":"4111111111111111",
    "card_holder_name":"Bob Smith",
    "exp_month":"01",
    "exp_year":"2018",
    "cvv":"123"
  },
  "billing_address":{
    "postal_code":"12345"
  }
}

 

Payment Authorization Webhook Object


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 12 for a complete list of Response Codes.)
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 2 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Not available when the response code is 'error'.
   payment Object
     transaction_id String[40] A unique identifier to associate with a payment request. This id is required to modify (i.e. 'capture', 'void', or 'credit') the payment later.
     authorization_number String Authorization number returned by the cardholder's financial institution when a transaction has been approved.
     avs_code String Result code for Address Verification(AVS).
     cvv_code String Result code for CVV Authentication (Returned from the bank - will be blank if CVV is not supported.)
     transaction_type String The type of transaction performed (Returned unmodified).
     amount Integer Payment amount in cents (Returned unmodified).
     currency String[3] Three-letter ISO currency code representing the currency in which the payment was made (Returned unmodified).
     client_transaction_id String[40] A client-defined value that can be used to internally identify the transaction (Returned unmodified).
     method String The payment method (Returned unmodified).
     credit_card Object The Credit Card Object (Returned with sensitive fields removed or masked).
     bank_account Object The Bank Account Object (Returned with sensitive fields removed or masked).
     wallet Object The Wallet Object (Returned with sensitive fields removed or masked).
     token Object The Payment Token Object (Returned with sensitive fields removed or masked).
     billing_address Object The Billing Address Object (Returned unmodified).
     merchant Object The Merchant Object

 

Payment Authorization Webhook Object


Example Payment Authorization Webhook Object

{
  "result": {
    "payment": {
      "merchant": {
       "merchant_id":"12345"
        "company_name": "Test Merchant",
        "address_line_1": "12345 Main St.",
        "address_line_2": "Suite 1000",
        "city": "Tacodowns",
        "state_province": "MA",
        "country_code": "US",
        "postal_code": "12203-1737",
        "email": "example@example.com",
        "phone_number": "555-555-1234",
        "terminal_id": "d0086724632b4bd39bf51da670c33816",
        "terminal_name": "My Terminal"
      },
      "transaction_type": "Sale",
      "amount": 111,
      "currency": "USD",
      "client_transaction_id": "AXB1233309",
      "transaction_id": "39420",
      "method": "Visa",
      "authorization_number": "TEST",
      "avs_code": "Y",
      "cvv_code": "M",
      "credit_card": {
        "card_type": "visa",
        "card_number": "****1111",
        "card_holder_name": "Bob Smith"
      },
      "billing_address": {
        "first_name": "Johnny",
        "last_name": "Bravo",
        "company_name": "Bravo Industries",
        "address_line_1": "245 Main St.",
        "address_line_2": "Suite 101",
        "city": "Templeton",
        "state_province": "VA",
        "country_code": "US",
        "postal_code": "01803-3747",
        "email": "example@example.com",
        "phone": {
          "number": "555-555-1212",
          "type": "Mobile"
        }
      }
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

 

Payment Authorization Webhook Tester


Appendix 1 - CVV and AVS Response Codes


 

CVV Response Codes

CVV Response Codes are returned for credit card transactions in which CVV Authentication is applicable. CVV refers to the 3 or 4-digit security number on the back (front for Amex) of the credit card.

Code Description
I Invalid Format
M CVV2/CVC2/CVD Match.
N CVV2/CVC2/CVD No Match.
P Not Processed.
S Match has indicated that CVV2/CVC2/CVD is not present on the card.
U Issuer is not certified and/or has not provided Visa encryption keys.

 

AVS Response Codes

AVS Response Codes are returned for credit card transactions in which Address Verification in required. Address Verification can be required on a per-merchant basis but can be overridden on a per-terminal basis.

Code Description
X Exact match, 9-character number ZIP.
Y Exact match, 5-character numeric ZIP.
A Address match only.
W 9-character numeric ZIP match only.
Z 5-character ZIP match only.
N No address or ZIP match only.
U Address unavailable.
G Non-North American issuer, does not participate.
R Issuer system unavailable.
E Not a mail/phone order.
S Service not supported.
Q Bill to address did not pass edit checks.
D International street address and postal code match.
B International address match only, ZIP not verified due to incompatible formats.
C International street address and post code not verified due to incompatible formats.
P International postal code match, street address not verified due to incompatible format.
1 Cardholder name matches.
2 Cardholder name, billing address, and postal code match.
3 Cardholder name and billing postal code match.
4 Cardholder name and billing address match.
5 Cardholder name incorrect, billing address and postal code match.
6 Cardholder name incorrect, billing postal code matches.
7 Cardholder name incorrect, billing address matches.
8 Cardholder name, billing address, and postal code are all incorrect.

Appendix 2 - Reason Codes


Code Response Message Response Type Description
001 Transaction Received Info                   This is sent to acknowledge that the submitted transaction has been received.
000 Approved Approved No action required.
010 Partially Approved Approved The authorized amount is less than the requested amount.
100 Processing Network Unavailable Soft Decline There is a problem with the card network. Contact the network for more information.
101 Issuer Unavailable Soft Decline There is a problem with the issuer network. Please contact the issuing bank.
102 Re-submit Transaction Soft Decline There is a temporary problem with your submission. Please re-submit the transaction.
108 Try again later Soft Returned if the eProtect token is not immediately available, when submitting an Auth or Sale transaction.
110 Insufficient Funds Soft Decline The card does not have enough funds to cover the transaction.
111 Authorization amount has already been depleted Hard Decline The total amount of the original Authorization has been used.
120 Call Issuer Referral or
Soft Decline
There is an unspecified problem, contact the issuing bank.
121 Call AMEX Referral There is an unspecified problem; contact AMEX.
122 Call Diners Club Referral There is an unspecified problem; contact Diners Club.
123 Call Discover Referral There is an unspecified problem; contact Discover.
124 Call JBS Referral There is an unspecified problem; contact JBS.
125 Call Visa/MasterCard Referral There is an unspecified problem; contact Visa or MasterCard.
126 Call Issuer - Update Cardholder Data Referral Some data is out of date; contact the issuer to update this information.
127 Exceeds Approval Amount Limit Hard Decline This transaction exceeds the daily approval limit for the card.
130 Call Indicated Number Referral There is an unspecified problem; contact the phone number provided.
140 Update Cardholder Data Referral Cardholder data is incorrect; contact the issuing bank.
150 Original transaction found. Info A Query transaction response indicating that the original transaction was found.
151 Original transaction not found. Info A Query transaction response indicating that the original transaction was not found.
152 Original transaction found, but response not yet available. Info A Query transaction response indicating that the original transaction was found, but the final response information is not yet available.
153 Query transaction not enabled. Info A Query transaction response indicating that you are not enabled for use of the Query transaction.
191 The merchant is not registered in the update program. N/A This is an Account Updater response indicating a set-up problem that must be resolved prior to submitting another request file. Escalate this to your Customer Experience Manager.
192 Merchant not certified/enabled for IIAS Hard Decline Your organization is not certified or enabled for IIAS/FSA transactions.
206 Issuer Generated Error Soft Decline An unspecified error was returned by the issuer. Please retry the transaction and if the problem persists, contact the issuing bank.
207 Pickup card - Other than Lost/Stolen Hard Decline The issuer indicated that the gift card should be removed from use.
209 Invalid Amount Hard Decline The specified amount is invalid for this transaction.
211 Reversal Unsuccessful Hard Decline The reversal transaction was unsuccessful.
212 Missing Data Hard Decline Contact your Customer Experience Manager.
213 Pickup Card - Lost Card Hard Decline The submitted card was reported as lost and should be removed from use.
214 Pickup Card - Stolen Card Hard Decline The submitted card was reported as stolen and should be removed from use.
215 Restricted Card Hard Decline The specified Gift Card is not available for use.
216 Invalid Deactivate Hard Decline The Deactivate transaction is invalid for the specified card.
217 Card Already Active Hard Decline The submitted card is already active.
218 Card Not Active Hard Decline The submitted card has not been activated.
219 Card Already Deactivate Hard Decline The submitted card has already been deactivated.
221 Over Max Balance Hard Decline The activate or load amount exceeds the maximum allowed for the specified gift Card.
222 Invalid Activate Hard Decline The activate transaction is not valid or can no longer be reversed.
223 No transaction Found for Reversal Hard Decline The transaction referenced in the reversal transaction does not exist.
226 Incorrect CVV Hard Decline The transaction was declined because it was submitted with the incorrect security code.
229 Illegal Transaction Hard Decline The transaction would violate the law.
251 Duplicate Transaction Hard Decline The transaction is a duplicate of a previously submitted transaction.
252 System Error Hard Decline Contact Customer Experience Manager.
253 Deconverted BIN Hard Decline The BIN is no longer valid.
254 Merchant Depleted Hard Decline No balance remains on gift Card.
255 Gift Card Escheated Hard Decline The Gift Card has been seized by the government while resolving an estate.
256 Invalid Reversal Type for Credit Card Transaction Hard Decline You attempted to use a Closed Loop Gift Card reversal transaction to reverse a credit card transaction. For example, you cannot use a Deposit Reversal transaction to reverse a Capture. To reverse a credit card Capture transaction, use a Credit transaction.
257 System Error(message format error) Hard Decline Issuer reported message format is incorrect. Contact Customer Experience Manager.
258 System Error(cannot process) Hard Decline Issuer reported transaction could not be processed. Contact Customer Experience Manager.
301 Invalid Account Number Hard Decline The account number is not valid; contact the cardholder to confirm information or inquire about another form of payment.
302 Account Number Does Not Match Payment Type Hard Decline The payment type was selected as one card type (e.g. Visa), but the card number indicates a different card type (e.g. MasterCard).
303 Pick Up Card Hard Decline This is a card present response, but in a card not present environment. Do not process the transaction and contact the issuing bank.
304 Lost/Stolen Card Hard Decline The card has been designated as lost or stolen; contact the issuing bank.
305 Expired Card Hard Decline The card is expired.
306 Authorization has expired; no need to reverse Hard Decline The original Authorization is no longer valid, because it has expired.
You cannot perform an Authorization Reversal for an expired Authorization.
307 Restricted Card Hard Decline The card has a restriction preventing approval for this transaction. Please contact the issuing bank for a specific reason.
You may also receive this code if the transaction was declined due to Prior Fraud Advice Filtering and you are using a schema version V8.10 or older.
308 Restricted Card - Chargeback Hard Decline This transaction is being declined due the operation of the Prior Chargeback Card Filtering Service or the card has a restriction preventing approval if there are any chargebacks against it.
309 Restricted Card - Prepaid Card Filtering Service Hard Decline This transaction is being declined due the operation of the Prepaid Card Filtering service.
310 Invalid track data Hard Decline The track data is not valid.
311 Deposit is already referenced by a chargeback Hard Decline The deposit is already referenced by a chargeback; therefore, a refund cannot be processed against the original transaction.
312 Restricted Card - International Card Filtering Service Hard Decline This transaction is being declined due the operation of the International Card Filtering Service.
313 International filtering for issuing card country <country> (where <country> is the 3-character country code) Hard Decline This is returned when the transaction involves a US based merchant processing Canadian transactions has a transaction that uses a US card.
315 Restricted Card - Auth Fraud Velocity Filtering Service Hard Decline This transaction is being declined due the operation of the Auth Fraud Velocity Filtering Service.
316 Automatic Refund Already Issued Hard Decline This refund transaction is a duplicate for one already processed automatically by the Fraud Chargeback Prevention Service (FCPS).
318 Restricted Card - Auth Fraud Advice Filtering Service Hard Decline This transaction is being declined due the operation of the Auth Fraud Advice Filtering Service.
319 Restricted Card - Fraud AVS Filtering Service Hard Decline This transaction is being declined due the operation of the Auth Fraud AVS Filtering Service.
320 Invalid Expiration Date Hard Decline The expiration date is invalid.
321 Invalid Merchant Hard Decline The card is not allowed to make purchases from this merchant (e.g. a Travel only card trying to purchase electronics).
322 Invalid Transaction Hard Decline The transaction is not permitted; contact the issuing bank.
323 No such issuer Hard Decline The card number references an issuer that does not exist. Do not process the transaction.
324 Invalid Pin Hard Decline The PIN provided is invalid.
325 Transaction not allowed at terminal Hard Decline The transaction is not permitted; contact the issuing bank.
326 Exceeds number of PIN entries Hard Decline (Referring to a debit card) The incorrect PIN has been entered excessively and the card is locked.
327 Cardholder transaction not permitted Hard Decline Merchant does not allow that card type or specific transaction.
328 Cardholder requested that recurring or installment payment be stopped Hard Decline Recurring/Installment Payments no longer accepted by the card issuing bank.
330 Invalid Payment Type Hard Decline This payment type is not accepted by the issuer.
331 Invalid POS Capability for Cardholder Authorized Terminal Transaction Hard Decline For a Cardholder Authorized Terminal Transaction, the POS capability must be set to magstripe.
332 Invalid POS Cardholder ID for Cardholder Authorized Terminal Transaction Hard Decline For a Cardholder Authorized Terminal Transaction, the POS Cardholder ID must be set to no pin.
335 This method of payment does not support authorization reversals Hard Decline You cannot perform an Authorization Reversal transaction for this payment type.
336 Reversal amount does not match Authorization amount. Hard Decline For a merchant initiated reversal against an American Express authorization, the reversal amount must match the authorization amount exactly.
340 Invalid Amount Hard Decline The transaction amount is invalid (too high or too low). For example, less than 0 for an authorization, or less than .01 for other payment types.
341 Invalid Healthcare Amounts Hard Decline The amount submitted with this FSA/Healthcare transaction is invalid. The FSA amount must be greater than 0, and cannot be greater than the transaction amount.
346 Invalid billing descriptor prefix Hard Decline The billing descriptor prefix submitted is not valid.
347 Invalid billing descriptor Hard Decline The billing descriptor is not valid because you are not authorized to send transactions with custom billing fields.
348 Invalid Report Group Hard Decline The Report Group specified in the transaction is invalid, because it is either not in the defined list of acceptable Report Groups or there is a mis-match between the Report Group and the defined Billing Descriptor.
349 Do Not Honor Soft Decline The issuing bank has put a temporary hold on the card.
350 Generic Decline Soft or Hard Decline There is an unspecified problem; contact the issuing bank for more details.
Note: This code can be a hard or soft decline, depending on the method of payment, and other variables.
351 Decline - Request Positive ID Hard Decline Card Present transaction that requires a picture ID match.
352 Decline CVV2/CID Fail Hard Decline The CVV2/CID is invalid.
354 3-D Secure transaction not supported by merchant Hard Decline You are not certified to submit 3-D Secure transactions.
356 Invalid purchase level III, the transaction contained bad or missing data Soft Decline Submitted Level III data is bad or missing.
357 Missing healthcareIIAS tag for an FSA transaction Hard Decline The FSA Transactions submitted does not contain the <healtcareIIas> data element.
358 Restricted by Litle due to security code mismatch. Hard Decline The transaction was declined due to the security code (CVV2, CID, etc.) not matching.
360 No transaction found with specified litleTxnId Hard Decline There were no transactions found with the specified litleTxnId.
361 Authorization no longer available Hard Decline The authorization for this transaction is no longer available. Either the authorization has already been consumed by another capture, or the authorization has expired.
362 Transaction Not Voided - Already Settled Hard Decline This transaction cannot be voided; it has already been delivered.
363 Auto-void on refund Hard Decline This transaction (both capture and refund) has been voided.
364 Invalid Account Number - original or NOC updated eCheck account required Hard Decline The submitted account number is invalid. Confirm the original account number or check NOC for new account number.
365 Total credit amount exceeds capture amount Hard Decline The amount of the credit is greater than the capture, or the amount of this credit plus other credits already referencing this capture are greater than the capture amount.
366 Exceed the threshold for sending redeposits Hard Decline NACHA rules allow two redeposit attempts within 180 days of the settlement date of the initial deposit attempt. This threshold has been exceeded.
367 Deposit has not been returned for insufficient/non-sufficient funds Hard Decline NACHA rules only allow redeposit attempts against deposits returned for Insufficient or Uncollected Funds.
368 Invalid check number Soft Decline The check number is invalid.
369 Redeposit against invalid transaction type Hard Decline The redeposit attempted against an invalid transaction type.
370 Internal System Error - Call Litle Hard Decline There is a problem with the system. Contact support@litle.com.
372 Soft Decline - Auto Recycling In Progress Soft Decline The transaction was intercepted because it is being auto recycled by the Recycling Engine.
373 Hard Decline - Auto Recycling Complete Hard Decline The transaction was intercepted because auto recycling has completed with a final decline.
375 Merchant is not enabled for surcharging Hard Decline The submitted transaction contained a surcharge and the merchant is not enabled for surcharging.
376 This method of payment does not support surcharging Hard Decline The use of a surcharge is only allowed for Visa and MasterCard methods of payment.
377 Surcharge is not valid for debit or prepaid cards Hard Decline You cannot apply a surcharge to a transaction using a debit or prepaid card.
378 Surcharge cannot exceed 4% of the sale amount Hard Decline The surcharge in the submitted transaction exceeded 4% maximum allowed for a surcharge.
380 Secondary amount cannot exceed the sale amount Hard Decline The secondary amount exceeded the sale amount in the submitted transaction.
381 This method of payment does not support secondary amount Hard Decline The submitted method of payment does not allow the use of Convenience Fees.
382 Secondary amount cannot be less than zero Hard Decline The secondary amount must be a positive integer.
383 Partial transaction is not supported when including a secondary amount Hard Decline Transactions set to allow partial authorizations cannot include a secondary amount.
384 Secondary amount required on partial refund when used on deposit Hard Decline If the associated sale or capture transaction included a secondary amount, an associated partial refund must include a secondary amount.
385 Secondary amount not allowed on refund if not included on deposit Hard Decline If the associated sale or capture transaction did not included a secondary amount, you cannot include a secondary amount on an associated refund.
401 Invalid E-mail Hard Decline The e-mail address provided is not valid. Verify that it was entered correctly.
469 Invalid Recurring Request - See Recurring Response for Details Hard Decline The Recurring Request was invalid, which invalidated the transaction. The Response Code and Message in the Recurring Response contains additional information.
470 Approved - Recurring Subscription Created Approved The recurring request was processed successfully.
471 Parent Transaction Declined - Recurring Subscription Not Created Hard Decline The original payment transaction was declined, so the recurring payments have not been scheduled.
472 Invalid Plan Code Hard Decline The plan specified in the recurring request was invalid.
473 Scheduled Recurring Payment Processed Approved The scheduled recurring payment has been processed successfully.
475 Invalid Subscription Id Hard Decline The referenced subscription Id does not exist.
476 Add On Code Already Exists Hard Decline The specified Add On code already exists.
477 Duplicate Add On Codes in Requests Hard Decline Multiple createAddOn requests submitted with the same Add On Code.
478 No Matching Add On Code for the Subscription Hard Decline The Add On code specified does not exist.
480 No Matching Discount Code for the Subscription Hard Decline The Discount Code supplied in the updateDiscount or deleteDiscount transaction does not exist.
481 Duplicate Discount Codes in Request Hard Decline Multiple createDiscount requests submitted with the same Discount Code.
482 Invalid Start Date Hard Decline The supplied Start Date is invalid.
483 Merchant Not Registered for Recurring Engine Hard Decline You are not registered for the use of the Recurring Engine.
500 The account number was changed Hard Decline An Account Updater response indicating the Account Number changed from the original number.
501 The account was closed Hard Decline An Account Updater response indicating the account was closed. Contact the cardholder directly for updated information.
502 The expiration date was changed N/A An Account Updater response indicating the Expiration date for the card has changed.
503 The issuing bank does not participate in the update program N/A An Account Updater response indicating the issuing bank does not participate in the update program.
504 Contact the cardholder for updated information N/A An Account Updater response indicating you should contact the cardholder directly for updated information.
505 No match found N/A An Account Updater response indicating no match was found in the updated information.
506 No changes found N/A An Account Updater response indicating there have been no changes to the account information.
521 Soft Decline - Card reader decryption service is not available Soft Decline The connection to the decryption service is currently unavailable. Please retry the transaction and/or contact your Customer Experience Manager.
523 Soft Decline - Decryption failed Soft Decline Our attempt to decrypt the card information failed. Please retry the transaction.
524 Hard Decline - Input data is invalid. Hard Decline The submitted data is invalid.
530 Apple Pay Key Mismatch Hard Decline The submitted publicKeyHash element does not match any configured entries. Contact your Implementation Consultant.
531 Apple Pay Decryption Failed Hard Decline Vantiv was unable to decrypt the submitted information.
550 Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold Hard Decline The transaction was declined because the resulting ThreatMetrix Fraud Score was below the acceptable threshold set in the merchant’s policy.
801 Account number was successfully registered Approved The card number was successfully registered and a token number was returned.
802 Account number was previously registered Approved The card number was previously registered for tokenization.
805 Card Validation Number Updated Approved The stored value for CVV2/CVC2/CID has been successfully updated.
820 Credit card number was invalid Hard Decline The card number submitted for tokenization is invalid.
821 Merchant is not authorized for tokens Hard Decline Your organization is not authorized to use tokens.
822 Token was not found Hard Decline The token number submitted with this transaction was not found.
835 Capture amount cannot be more than authorized amount Hard Decline The amount in the submitted Capture exceeds 115% of the authorized amount.
850 Tax Billing only allowed for MCC 9311 Hard Decline Tax Billing elements are allowed only for MCC 9311.
851 MCC 9311 requires taxType element Hard Decline Missing taxType element.
852 Debt Repayment only allowed for VI transactions on MCCs 6012 and 6051 Hard Decline You must be either MCC 6012 or 6051 to designate a Visa transaction as Debt Repayment (debtRepayment element set to true).
877 Invalid Pay Page Registration Id Hard Decline An eProtect response indicating that the Registration ID submitted is invalid.
878 Expired Pay Page Registration Id Hard Decline An eProtect response indicating that the Registration ID has expired (Registration IDs expire 24 hours after being issued).
879 Merchant is not authorized for Pay Page Hard Decline Your organization is not authorized to use eProtect.
898 Generic token registration error Soft Decline There is an unspecified token registration error; contact your Customer Experience Manager.
899 Generic token use error Soft Decline There is an unspecified token use error; contact Customer Experience Manager.
900 Invalid Bank Routing Number Hard Decline The eCheck routing number submitted with this transaction has failed validation.
950 Decline - Negative Information on File Hard Decline An eCheck response indicating the account is on the negative file.
951 Absolute Decline Hard Decline An eCheck response indicating that this transaction was declined.
952 The Merchant Profile does not allow the requested operation Hard Decline An eCheck response indicating that your Merchant Profile does not allow the requested operation. Contact your Customer Experience Manager for additional information.
953 The account cannot accept ACH transactions Hard Decline An eCheck response indicating the customer’s checking account does not accept ACH transactions.
954 The account cannot accept ACH transactions or site drafts Hard Decline An eCheck response indicating the customer’s checking account does not accept ACH transactions or site drafts.
955 Amount greater than limit specified in the Merchant Profile Hard Decline An eCheck response indicating that the dollar amount of this transaction exceeds the maximum amount specified in your Merchant Profile. Contact your Customer Experience Manager for additional information.
956 Merchant is not authorized to perform eCheck Verification Hard Decline An eCheck response indicating that your organization is not transactions authorized to perform eCheck verifications. Contact your Customer Experience Manager for additional information.
957 First Name and Last Name required for eCheck Verifications Hard Decline An eCheck response indicating that the first and last name of the customer is required for eCheck verifications.
958 Company Name required for corporate account for eCheck Verifications Hard Decline An eCheck response indicating that the company name is required for verifications on corporate accounts.
959 Phone number required for eCheck Verifications Hard Decline An eCheck response indicating that the phone number of the customer is required for eCheck verifications.
961 Card Brand token not supported Hard Decline This code is returned if the merchant submits a Visa generated token.
962 Private Label Card not supported Hard Decline This code is returned if the transaction involves a Visa Private Label card.
F01 AVS is required
F02 CVV is required
F03 Exceeds amount limit
F04 Exceeds credit amount limit
F05 Exceeds daily amount limit
F06 Exceeds daily credits amount limit
F07 Exceeds weekly amount limit
F08 Exceeds weekly credits amount limit
F09 Exceeds daily count limit
F10 Exceeds daily credits count limit
F11 Exceeds weekly count limit
F12 Exceeds weekly credits count limit
E01 Invalid Request: Credit Card is required
E02 Invalid Request: Cardholder's Name is required
E03 Invalid Request: Card Expiration is required
E04 Invalid Request: Bank Account is required
E05 Invalid Request: Bank Routing Number is required
E06 Invalid Request: Bank account holder's Name is required
E07 Invalid Request: Token is required
E08 Invalid Request: Amount is required
E09 Invalid Request: Credit Amount exceeds original
E10 Invalid Credit Card Number
E11 Invalid Card Expiration
E12 Invalid CVV
E13 Invalid Account Type
E14 Invalid Bank Account Type
E15 Invalid Bank Routing Number
E16 Invalid Token Type
E17 Invalid Token
E18 Invalid Transaction ID
E19 Invalid Transaction Type
E20 Invalid Credentials
E21 Invalid Payment Method
E22 Invalid Content-Type
E23 Request Expired
E24 Invalid Request: Capture Amount exceeds original
E25 Invalid Request: Transaction ID is required
E26 Invalid Bank Account Number
E27 Invalid Request: Account holder's Name is required
E28 Invalid Request: Card Not Accepted
E29 Invalid Request: eCheck Not Accepted
E30 Invalid Gateway ID
E31 Invalid Request: Void Amount does not match original
E32 Invalid SEC Code
E97 Invalid Request: Processor Error
E98 Invalid Request: Validation Error
E99 Invalid Request: Unknown Error

Appendix 3 - Transaction Types


This Appendix lists all of the valid "transaction_type" values.

Type Description
Sale A transaction of type 'sale' is submitted and immediately flagged for settlement.
Authorize A transaction of type 'authorize' is authorized immediately, but will not be flagged for settlement. These transactions must be flagged for settlement using a transaction of type 'capture'. Authorizations typically remain active for three to seven business days.
(Not available for eCheck, eCheck_token, or eCheck_wallet Transactions)
Capture A transactions of type 'capture' will flag an existing authorization for settlement. Only 'authorize' transactions can be captured. The transaction amount for a 'capture' transaction may not exceed the amount of the original 'authorize' transaction.
(Not available for eCheck, eCheck_token, or eCheck_wallet Transactions)
Void Transactions of type 'void' will cancel an existing sale or captured authorization. In addition, non-captured 'authorize' transactions can be voided to prevent any future capture. Voids can only occur if the transaction has not been settled.
Credit Transactions of type 'credit' will reverse a previously-settled transaction. If the transaction has not been settled, perform a 'void' transaction instead of a 'credit'.

Appendix 4 - Standard Entry Class (SEC) Codes


This Appendix lists all of the valid "sec_code" values.

Code Description
PPD Preauthorized Pay/Deposit
  • Direct Deposit (credit) - A credit application that transfers funds into a consumer’s account at the receiving depository financial institution. The funds being deposited can represent a variety of products (payroll, interest, pension, dividends, etc).
  • Preauthorized Bill Payment (debit) - A debit application. Companies with billing operations may participate in the ACH through the electronic transfer (direct debit) of bill payment entries. Through standing authorizations, the consumer grants the company authority to initiate periodic charges to his or her account as bills become due. This concept has met with appreciable success in situations where the recurring bills are regular and do not vary in amount (insurance premiums, mortgage payments, installment loan payments, etc.). Standing authorizations have also been successful for bills where the amount does vary, such as utility payments.
CCD Corporate Credit or Debit
Can be either a credit or debit application where funds are either distributed or consolidated between corporate entities. This application can serve as a stand-alone funds transfer, or it can support a limited amount of payment related data with the funds transfer.
WEB Internet Initiated/Mobile Entry
Used for the origination of debit entries (either Single or Recurring Entry) to a consumer’s account pursuant to an authorization that is obtained from the Receiver via the Internet. This SEC Code helps to address unique risk issues inherent to the Internet payment environment through requirements for added security procedures and obligations.

Appendix 5 - Payment Methods

This Appendix lists all of the valid "method" values. Depending on the payment method you use, you will be required to send in a specific payment method object containing account data. See Payment Method Objects below for more details.

Payment Method Description
credit_card Credit Card (Non-Swipe)                   
card_track Swiped Credit Card
echeck eCheck (ACH)
card_token Credit Card Token
echeck_token eCheck (ACH) Token
wallet A Customer Wallet
epic_token Epic Token

Appendix 6 - Payment Method Objects

Some API Methods require a Payment Method Object. This appendix shows the structure of each Payment Method Object.

 

Credit Card Object


Use this if "method" is 'credit_card' or 'card_track'.

Property Description
card_number String (Required) Credit card number.
card_holder_name String[50] (Required) Cardholder's name.
exp_month String (Required) Expiration month. (2-digit: "01" - "12")
exp_year String (Required) Expiration year. (4-digit)
cvv String[4] (Optional) Three-digit card verification code found on signature strip on the back of most credit card or four-digit on the front of American Express credit card.
    -OR- (Omit all of the above properties if you provide a 'card_track'.)
card_track String[350] The data from track 1 of a credit card's magnetic stripe (acquired using a credit card reader).

 

Bank Account Object


Use this if "method" is 'echeck'. All properties are required.

Property Description
account_type String Bank account types. (Values: 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
routing_number String[9] 9-digit Bank routing number. Must pass Mod 10 validation check.
account_number String[17] Bank account number.
account_holder_name String[50] Bank account holder's name.

 

Wallet Object


Use this if "method" is 'wallet'.

Property Description
wallet_id String (Required) Wallet ID
cvv String[4] (Optional: Applicable only to credit card wallet) Three-digit card verification code found on signature strip on the back of most credit card or four-digit on the front of American Express credit card.

 

Payment Token Object


Use this if "method" is 'card_token' or 'echeck_token'. This object can be a Multi-Use Token or One-time token.

Property Description
token_type String (Required) Token type. (Values: 'epicpay', 'litle')
token_number String (Required) Token number.
account_holder_name String[50] (Required) Account holder's name.
exp_month String (Required when "method" is 'card_token') Expiration month. (2-digit: "01" - "12")
exp_year String (Required when "method" is 'card_token') Expiration year. (4-digit)
cvv String[4] (Required when "method" is 'card_token' and the terminal requires cvv authorization. By default, terminals do not require cvv authorization.) Three-digit card verification code found on signature strip on the back of most credit card or four-digit on the front of American Express credit card.

 

Epic Token Object


Use this if "method" is 'epic_token'.

Property Description
token_type String (Required) Token type. (Values: 'card_token', 'echeck_token', 'wallet_token', 'checkout_token')
token_data String (Required) Token number. When "token_type" is 'card_token' or 'echeck_token', this value should contain the 'token_number' value. For 'wallet_token', use the 'wallet_id' value. For 'checkout_token', use the 'checkout_token' value.
account_holder_name String[50] (Required when "token_type" is 'card_token' or 'echeck_token') Account holder's name.
exp_month String (Required when "token_type" is 'card_token') Expiration month. (2-digit: "01" - "12")
exp_year String (Required when "token_type" is 'card_token') Expiration year. (4-digit)
cvv String[4] (Required when the terminal requires cvv authorization and the "token_type" is 'card_token' or when using a wallet token or checkout token for type: credit card)
Three-digit card verification code found on signature strip on the back of most credit card or four-digit on the front of American Express credit card.

Appendix 7 - Contact Info Objects

Some API Methods allow or require contact information to be provided. This appendix shows the structure of each of Contact Info object.

 

Billing Address Object


If AVS is required on your terminal or merchant account, you will not be able to process credit card transactions without providing either "address" or "postal code".

Property Description
first_name String[20] Account holder's first name.
last_name String[20] Account holder's last name.
company_name String[50] Account holder's company name.
address_line_1 String[100] Account holder's billing address line 1.
address_line_2 String[20] Account holder's billing address line 2.
city String[50] Account holder's billing city.
state_province String[50] Account holder's billing state or province.
postal_code String[10] Account holder's billing postal code.
country_code String[2] Account holder's billing country code. (Default: 'US')
email String[256] Account holder's email address.
phone Object Account holder's Phone Object.

 

Customer Address Object


Property Description
first_name String[20] (Required) Customer's first name.
last_name String[20] (Required) Customer's last name.
company_name String[50] Customer's company name.
address_line_1 String[100] Customer's address line 1.
address_line_2 String[20] Customer's address line 2.
city String[50] Customer's city.
state_province String[50] Customer's state or province.
postal_code String[10] Customer's postal code.
country_code String[2] Customer's country code. (Default: 'US')
email String[256] Customer's email address.
phone Object Customer's Phone Object.

 

Phone Object


Property Description
number String[20] Phone number.
type String Phone type. (Values: 'landline', 'fax', 'mobile')

 

Merchant Object


Property Description
company_name String[50] Merchant's company name.
address_line_1 String[100] Merchant's address line 1.
address_line_2 String[20] Merchant's address line 2.
city String[50] Merchant's city.
state_province String[50] Merchant's state or province.
postal_code String[10] Merchant's postal code.
country_code String[2] Merchant's country code. (Default: 'US')
email String[256] Merchant's email address.
phone_number String[20] Merchant's phone number.
terminal_id String[32] Unique Identifier for the Terminal.
terminal_name String[50] Name of the Terminal.
merchant_id String[10] Unique Identifier for the Merchant.

Appendix 8 - Test Account Numbers


This appendix lists several test account numbers that can be used to safely test the API.

Account Type Number Expected Response
eCheck 01234567890123 Received
eCheck 01234567890123456 Received
American Express 371449635398431 Approved
American Express 378282246310005 Approved
Diner's Club 30569309025904 Approved
Diner's Club 38520000023237 Approved
Discover 6011000990139424 Approved
Discover 6011000400000000 Approved
JCB 3530111333300000 Approved
JCB 3566002020360505 Approved
Mastercard 5105105105105100 Approved
Mastercard 5200828282828210 Approved
Visa 4012888888881881 Approved
Visa 4111111111111111 Approved
Discover 6011111111111117 Declined (Insufficient funds)
Mastercard 5555555555554444 Declined (Insufficient funds)
Visa 4242424242424242 Declined (Insufficient funds)
Invalid eCheck Number 012 Error (Invalid Bank Account Number)
Invalid Credit Card Number 4111111111111112 Error (Invalid Credit Card Number)
Invalid Credit Card Number 5105105105105105 Error (Invalid Credit Card Number)

Appendix 9 - ACH Return Reason Codes


This appendix contains a list of ACH Return Reason Codes, which can apply to either eCheck transactions, or Dynamic Payout funding instructions.

Note: If an eCheck is returned for reason Code R01 or R09, it is eligible for redeposit.

Code Description
R01 Insufficient funds in account.
R02 Account is closed.
R03 No account on file.
R04 Invalid account number.
R05 Unauthorized debit to consumer account.
R06 Returned at request of ODFI.
R07 Authorization revoked by customer.
R08 Payment stopped.
R09 Insufficient collected funds in account being charged.
R10 Customer advises not Authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document.
R11 Check truncation return.
R12 Account sold to another financial institution.
R13 Invalid ACH routing number.
R14 Representative payee is deceased or cannot continue in that capacity.
R15 Beneficiary or account holder other than representative payee deceased.
R16 Account funds have been frozen.
R17 Item returned because of invalid data; refer to addenda for information.
R18 Improper effective date.
R19 Amount error.
R20 Account does not allow ACH transactions or limit for transactions has been exceeded.
R21 Invalid company identification.
R22 Invalid individual ID.
R23 Credit entry refused by receiver.
R24 Duplicate entry.
R25 Addenda record error.
R26 Mandatory field error.
R27 Trace number error.
R28 Routing/transit number check digit error.
R29 Corporate customer advised not authorized.
R30 RDFI not participant in check truncation program.
R31 Permissible return entry.
R32 RDFI non-settlement.
R33 Return of item.
R34 Limited participation ODFI.
R35 Return of improper debit entry.
R36 Return of improper credit entry.
R37 Source document presented for payment.
R38 Stop payment on source document.
R39 Improper source document.
R40 Return of item by government agency.
R41 Invalid Transaction Code.
R42 Routing/transit number check digit error.
R43 Invalid account number.
R44 Invalid individual ID.
R45 Invalid individual name or company name.
R46 Invalid representative payee indicator code.
R47 Duplicate enrollment.
R50 State law affecting RCK acceptance.
R51 Item is ineligible, notice not provided, signature not genuine, or original item altered for adjustment entry.
R52 Stop payment on item.
R53 Item and ACH entry presented for payment.
R61 Misrouted return - RDFI for original entry has placed incorrect routing/transit number in RDFI identification field
R67 Duplicate return.
R68 Untimely return - return was not sent within the established timeframe.
R69 Field errors.
R70 Permissible return entry not accepted.
R71 Misrouted dishonored return -incorrect routing/transit number in RDFI identification field.
R72 Untimely return - dishonored return was not sent within the established timeframe.
R73 Timely original return - RDFI certifies the original return entry was sent within established timeframe for original returns.
R74 Corrected return - RDFI is correcting a previous return entry that was dishonored because it contained incomplete or incorrect information.
R75 Original return not a duplicate.
R76 No errors found.
R80 Cross-border payment coding error.
R81 Non-participant in cross-border program.
R82 Invalid foreign RDFI identification.
R83 Foreign RDFI unable to settle.
R84 Cross-border entry not processed by originating gateway operator.
R94 Administrative return item was processed and resubmitted as a photocopy.
R95 Administrative return item was processed and resubmitted as a MICR-Split.
R97 Administrative return item was processed and resubmitted with corrected dollar amount.
R98 Indicates a return PAC (pre-authorized check); RDFI provides a text reason and indicated a new account number on the PAC itself.
R99 Indicates a return PAC (pre-authorized check); RDFI provides a text reason on the PAC itself for which there is no equivalent return reason code.

Appendix 10 - ACH NoC Change Codes


This appendix contains a list of ACH NoC Change Codes.

Code Description
C01 Incorrect account number.
C02 Incorrect routing/transit number.
C03 Incorrect routing/transit number and incorrect account number.
C04 Incorrect account name.
C05 Incorrect transaction code.
C06 Incorrect account number and transaction code.
C07 Incorrect routing/transit number, account number and transaction code.
C08 Incorrect foreign RDFI identification.
C09 Incorrect individual ID.
C13 Addenda format error.
C61 Misrouted NOC.
C62 Incorrect trace number.
C63 Incorrect company ID.
C64 Incorrect individual ID.
C65 Incorrectly formatted correct data.
C66 Incorrect discretionary data.
C67 Routing/transit number not from original entry.
C68 Account number not from original entry.
C69 Incorrect transaction code.
C96 Administrative return dishonor (dollar amount will be zero).
C99 Converted to MICR draft (check conversion items).

Appendix 11 - Metadata Properties


This appendix lists all EpicPay defined properties that may be present in the "metadata" collection.  

Property Description
designation String The unique name of the designation chosen by the user for the transaction.
donation String Present whenever the transaction is marked as a donation. (Values: "true")

Appendix 12 - Transaction Response Codes


This appendix describes the values returned in the "response_code" field of the "status" object found in a response.  

Response Code Description
Approved Indicates a successful credit card sale or authorization request.
Received Indicates a successful credit card capture or credit request, eCheck sale or credit request, or a void of any type of payment request.
Declined Indicates a failed credit card sale or authorization request. The declines will occur whenever a request has passed all internal validations, but has failed at the processor. See Appendix 2 for more details on Reason Code and Reason Text.
Error Indicates a failed request of any transaction type or payment method. Errors will occur whenever the request fails internal validation, or enounters a communication or network error. See Appendix 2 for more details on reason code and reason text.

Appendix 13 - Card Types


This appendix describes the values returned in the "card_type" field inside any "credit_card" object found in a response.

Card Type card_type                                                                             
American Express american_express
Diner's Club diners_club
Discover discover
JCB jcb
Mastercard mastercard
Visa visa

Revision History


Version Revision Date Description
1 9/05/2019 Added sec_code and entry_description for eCheck subscriptions. Both are also visible using Get Transaction.
1 8/28/2019 Added Appendix 12 that details transaction response codes.
1 8/09/2019 Added the metadata object to the GetTransaction response.
1 6/26/2019 Added is_test parameter to Sale/Authorize Transaction documentation. Improved descriptions for SEC codes.
1 6/07/2018 Added validation to restrict allowed characters in the Client Identifier fields.
1 5/04/2018 Added two new methods for activating and deactivating recurring payment subscriptions.
1 7/03/2017 The nonspecific "Database Error" responses for field length violations have been improved to show scenario-specific error messages.
1 5/17/2017 Improved the "Reason Text" for various invalid request scenarios.
1 4/21/2017 The "One-Time-Tokenization Library" was updated to support callback methods.
1 4/17/2017 The "RegisterToken" method was modified to allow generation of a Multi-Use token using a One-Time-Use token.
1 4/12/2017 Added new read-only method: GetTransaction.
1 2/21/2017 Added support for Create / Read / Update of Recurring Payments and Wallets.
1 2/14/2017 Added support for Card Swipe.