Payment API


 

Introduction


The EpicPay Gateway Payment API is a web service that allows third-party applications to process payments 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 Payment 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 Payment API.

 

API Version and Base URL

This documentation is for EpicPay Gateway Payment API Version 1.0

Base URL

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

NOTE: Endpoints are case-sensitive and must be in all lowercase.
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.
Note: All requests must be made over TLS/SSL.

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. For security reasons, all API requests that use Basic Authentication must be made from the server-side.

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 and Authorize Transactions:

The Sale and Authorize method can be used to perform the following transaction types:

  • Credit Card Transaction:
    • Credit Card Sale: Use "sale" as the "transaction_type" and use "credit_card", "card_track", or "epic_token" as the "method". Fulfill any conditional requirements for the given "method".
    • Credit Card Auth: Use "authorize" as the "transaction_type" and use "credit_card", "card_track", or "epic_token" as the "method". Fulfill any conditional requirements for the given "method".
  • ACH/EFT Debit / eCheck Sale: Use "sale" as the "transaction_type" and use "echeck" or "epic_token" as the "method". Fulfill any conditional requirements for the given "method".

To read more about these transaction types, see Appendix 1 - Transaction Types.

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • amount:Integer Transaction amount in cents.

    • currency:String[3] 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 when "method" is 'echeck', 'echeck_token', or 'wallet' using 'eCheck' method).

    • 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').

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

    • billing_address:Object The Contact Object for the billing address (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.)

    • order_details:Object The Order Details Object, which provides additional data for Level II and Level III processing for bank card transactions (Required if using Level II or Level III processing).

    Optional:

    • client_transaction_id:String[40] 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] 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] 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[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).

    • cof_processing_type:String[30] The type of transaction from the perspective of the Credential On File (COF) mandate. This property is provided solely for merchants who store raw credit card data or multi-use tokens within their own system as well as merchants who manage their own scheduling of recurring payments, in order to facilitate COF compliance. (Values: see Appendix 10)

    • network_transaction_id:String The network-specific unique identifier for this transaction. This property is provided solely for merchants who store raw credit card data or multi-use tokens within their own system as well as merchants who manage their own scheduling of recurring payments, in order to facilitate COF compliance.

    • 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')

    • email_receipt:Boolean Indicates whether a transaction receipt should be sent via email to the purchaser. To successfully send the receipt, an email address must be provided within the billing_address object.

    • shipping_address:Object The Contact Object for the shipping address, indicating where products will be shipped. If unset, billing_address will be used.  

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.
  • Canadian merchants must use the currency "CAD" when submitting eCheck transactions.
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').
epic_token Object The Epic Token Object (Required if "method" is 'epic_token').
sec_code String[3] Standard Entry Class (SEC) Codes for ACH(eCheck) Transactions (Required when "method" is 'echeck', 'echeck_token', or 'wallet' using 'eCheck' method).
billing_address Object The Contact Object for the billing address (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).
order_details Object The Order Details Object, which provides additional data for Level II and Level III processing for bank card transactions (Required if using Level II or Level III).
cof_processing_type String[30] (Optional) The type of transaction from the perspective of the Credential On File (COF) mandate. This property is provided solely for merchants who store raw credit card data or multi-use tokens within their own system as well as merchants who manage their own scheduling of recurring payments, in order to facilitate COF compliance. (Values: see Appendix 10)
network_transaction_id String (Optional) The network-specific unique identifier for this transaction. This property is provided solely for merchants who store raw credit card data or multi-use tokens within their own system as well as merchants who manage their own scheduling of recurring payments, in order to facilitate COF compliance.
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')
email_receipt Boolean (Optional) Indicates whether a transaction receipt should be sent via email to the purchaser. To successfully send the receipt, an email address must be provided within the billing_address object.
shipping_address Object (Optional) The Contact Object for the shipping address, indicating where products will be shipped. If unset, billing_address will be used.

 

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 Request (Sale, 3D Secure Enabled)

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",
    "authentication":{
      "cryptogram": "Base64EncodedString==",
      "authentication_id": "abc123",
      "eci_indicator": "05",
      "source": "network_3ds_v1"
    }
  },
  "billing_address":{
    "postal_code":"12345"
  }
}

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 (Sale: Credit Card Epic Token)

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

{
  "amount":"100",
  "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":"100",
  "currency":"usd",
  "method":"epic_token",
  "transaction_type":"sale",
  "sec_code":"web",
  "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":"100",
  "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 using Epic Token)

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

{
  "amount":"100",
  "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":"100",
  "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"
  }
}

Digital Wallets Overview


The EpicPay Gateway offers support for E-Wallet or 3rd party tokenization services including Apple Pay and Google Pay.

Typically, a 3rd-party tokenization workflow will look like this:

  1. Your application or website initiates a transaction by placing a request to a 3rd-party tokenization provider (Apple Pay, Google Pay, etc.).
  2. The provider returns encrypted, tokenized data back to the your application/website within the response payload.
  3. The application/website takes the tokenized data from the response payload and sends it in a request to the EpicPay Gateway Payment API to complete the transaction.
  4. The EpicPay Gateway attempts to complete the transaction, and informs your application/website of the result.

This section provides guidance on how to complete Apple Pay and Google Pay payments by passing their respective tokenized data to the EpicPay Gateway Payment API using the Sale or Authorize method.

NOTE: When submitting third-party token_data, the string must be Base64 encoded.

Apple Pay


Once a customer successfully initiates a transaction on your website or application using Apple Pay, tokenized payment information will be returned to the website/application in the form of a complex JavaScript object. In order to complete the payment, the EpicPay Gateway requires the ApplePayPaymentToken object within this response.

The ApplePayPayment response object will appear similar to this when interpreted as JSON:

ApplePayPayment: {
"token": ApplePayPaymentToken,
    "billingContact": ApplePayPaymentContact,
    "shippingContact": ApplePayPaymentContact
}

To input the ApplePayPaymentToken into the EpicPay Gateway Payment API, convert the value of the "token" property into a JSON string, then convert the string to Base64 , and finally place it in “token_data” within the “epic_token” object of a Sale or Authorize request.

 

When submitting the Sale or Authorize request, ensure that:

  • The "method" is set to "third_party_token"
  • The "epic_token" object is populated:
    • The "token_type" is set to "apple_pay".
    • "token_data" contains the JSON stringified and Base64 encoded value found in the token property of Apple Pay's response.

Example Sale or Authorize Request using Apple Pay Token Data:

{
    "amount": "111",
    "currency": "usd",
    "method": "third_party_token",
    "transaction_type": "sale",
    "epic_token": {
        "token_type": "apple_pay",
        "token_data": "BASE64_Encoded_JSON_String==",
        "account_holder_name": "Bob Doe"
    }
}

Note: To view the class structure of the Apple Pay response in greater detail, please visit the Apple Pay developer documentation .

Google Pay™


Introduction

The EpicPay Gateway supports Google Pay transactions directly through the Payment API or through a Donation page. This section is intended for developers integrating their Google Pay workflow directly through the Payment API.

To enable Google Pay for Donation pages, you must read and agree to the Google Pay API Terms of Service and Google Pay APIs Acceptable Use Policy . Then, contact your Fortis relations manager.

The EpicPay Gateway supports both PAN-only and 3DS authorization methods for Google Pay, and supports the following card networks for use with Google Pay: American Express, Discover, JCB, Mastercard, and Visa.

 

Integration Guide

In order to initiate a transaction, your website or application must send a request to the Google Pay API specifying a payment method using their PaymentMethod object. If the payment is to be made using the EpicPay Gateway, the PaymentMethod must be properly configured:

Under "parameters", set the following properties:

  • For "allowedAuthMethods", use ["PAN_ONLY", "CRYPTOGRAM_3DS"].
  • For "allowedCardNetworks", use ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"].

Under "tokenizationSpecification" and "parameters", set the following properties:

  • For "gateway", use "epicpay".
  • For "gatewayMerchantId", use your EpicPay Gateway Merchant ID.

Example GooglePay PaymentMethod:

{
    "type": "CARD",
    "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
    },
    "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
            "gateway": "epicpay",
            "gatewayMerchantId": {{Your EpicPay Gateway Merchant ID}}
        }
    }
}

 

Once a customer successfully initiates a transaction on your website or application using Google Pay, a PaymentData object will be returned in the response. In order to complete the payment, the EpicPay Gateway only requires the value of the “token” property within the response, which will be in a JSON string format.

The PaymentData Response will look similar to this:

{
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "paymentMethodData": {
        "type": "CARD",
        "description": "Visa...1234",
        "info": { ... },
        "tokenizationData": {
            "type": "PAYMENT_GATEWAY",
"token": "Token Data JSON string"
        }
    }
}

To input the "token" value into the EpicPay Gateway Payment API, convert the value of the "token" property to Base64 , and then place it in “token_data” within the “epic_token” object of a Sale or Authorize request.

 

When submitting the Sale or Authorize request, ensure that:

  • The "method" is set to "third_party_token"
  • The "epic_token" object is populated:
    • The "token_type" is set to "google_pay".
    • "token_data" contains the Base64 encoded value found in the token property of Google Pay's response.
  • If your terminal requires AVS verification, a "billing_address" is provided. The "billing_address" must contain a "postal_code" and/or an "address_line_1".

Example Sale or Authorize Request using Apple Pay Token Data:

{
    "amount": "111",
    "currency": "usd",
    "method": "third_party_token",
    "transaction_type": "sale",
    "epic_token": {
        "token_type": "google_pay",
        "token_data": "BASE64_Encoded_JSON_String==",
        "account_holder_name": "Bob Doe"
    }
}

 

Note: For additional information on Google Pay integration for web merchants, please see the following links to Google Pay's developer documentation:

For Android merchants, see Google Pay's Android developer documentation:

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 2 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.
     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).
     network_transaction_id String The network-specific unique identifier for this transaction. This property is provided solely for merchants who store raw credit card data or multi-use tokens within their own system as well as merchants who manage their own scheduling of recurring payments, in order to facilitate COF compliance.
     authentication_response String Indicates the success or failure of a 3DS-enabled transaction. See Authentication Response Values for a complete list of possible values.
     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 Contact Object for the billing address (Returned unmodified).
     shipping_address Object The Contact Object for the shipping address, indicating where products will be shipped (Returned unmodified).
     order_details Object The Order Details Object, listing additional information about the order (Returned unmodified).

 

Example Response (Sale: Credit Card)

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

{
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "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": "Bob",
        "last_name": "Smith",
        "postal_code": "12345"
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      },
      "network_transaction_id":"12345678"
    }
  },
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  }
}

 

Example Response (Sale: Credit Card - TEST MODE)

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

{
  "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"
      }
    },
  },
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved-TEST MODE"
  }
}

 

Example Response (Sale: Credit Card, 3D Secure Enabled)

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

{
  "result": {
    "payment": {
      "transaction_type": "sale",
      "amount": 111,
      "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": "Bob",
        "last_name": "Smith",
        "postal_code": "12345"
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      },
      "network_transaction_id": "12345678",
      "authentication_response": "passed"
    }
  },
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  }
}

Address Verification Service (AVS)


Introduction

The Address Verification Service (AVS) is a tool offered by card companies to monitor fraud on a per-transaction basis. When a payment is submitted with card and billing address information, it is compared to the information on file with the card issuer. The issuer then returns an AVS code that describes how well the data compares. The EpicPay Gateway Payment API provides this code instantaneously within the response with each Sale / Authorize request. It is up to the merchant's discretion to decide which codes are permissible and which should be voided or otherwise canceled.

 

Requirements for AVS

AVS information includes the cardholder's address and postal code, which should be provided for all transactions in which a credit card authorization occurs (Credit card transactions of type "Sale" and "Authorize"). Provide these values using the billing_address object for all applicable transaction requests. (See: Sale/Authorize).

 

AVS Handling

For all transactions in which a credit card authorization occurs, (Credit card transactions of type "Sale" and "Authorize"), the response payload will contain an AVS Code property avs_code, which indicates the status of the address verification (See: Sale/Authorize). A complete list of AVS response codes is available in Appendix 1 – AVS Response Codes. It is recommended that all integrators incorporate logic in their applications that will review the AVS response code for each transaction. It is the responsibility of the merchant to submit a "Void / Authorization Reversal" when a transaction response contains an AVS Response Code that indicates a failure or partial failure to verify the cardholder's address.

 

Void / Capture / Refund Transactions:

The VCR method can be used to perform the following transaction types:

  • Void / Reversal:
    • Credit Card Authorization Reversal: Use "void" as the "transaction_type" on a previous Authorize with the full "amount" of the original transaction.
    • Credit Card Void - Sale: Use "void" as the "transaction_type" on a previous Sale with the full "amount" of the original transaction.
    • Credit Card Void - Capture: Use "void" as the "transaction_type" on a previous Capture with the full "amount" of the original transaction.
    • Credit Card Void - Credit / Refund: Use "void" as the "transaction_type" on a previous Credit with the full "amount" of the original transaction.
    • ACH Void - Sale: Use "void" as the "transaction_type" on a previous ACH Debit / eCheck Sale with the full "amount" of the original transaction.
    • ACH Void - Credit / Refund: Use "void" as the "transaction_type" on a previous ACH / eCheck Credit with the full "amount" of the original transaction.
  • Capture / Complete:
    • Capture - Full: Use "capture" as the "transaction_type" on a previous Authorize with the full "amount" of the original transaction.
    • Capture - Partial: Use "capture" as the "transaction_type" on a previous Authorize with an "amount" less than the original transaction. This will cause the remainder of the authorization amount to be reversed.
  • Refund / Return / Credit:
    • Credit Card Refund - Full: Use "credit" as the "transaction_type" on a previous Credit Card Sale or Capture with the full "amount" of the original transaction.
    • Credit Card Refund - Partial: Use "credit" as the "transaction_type" on a previous Credit Card Sale or Capture with an "amount" less than the original transaction.
    • ACH Refund / Credit - Full: Use "credit" as the "transaction_type" on a previous ACH Debit / eCheck Sale with the full "amount" of the original transaction.
    • ACH Refund / Credit - Partial: Use "credit" as the "transaction_type" on a previous ACH Debit / eCheck Sale with an "amount" less than the original transaction.

Note:

  • If a Sale or Capture transaction has not yet settled and is still voidable, an attempt to issue a Full Refund will be converted to a Void automatically.
  • Partial refunds cannot be performed on unsettled Sale or Capture Transaction. It is recommended to void the transaction and create a new sale or capture instead.

To read more about these transaction types, see Appendix 1 - Transaction Types.

  • URL

    BaseURL/authorize/transaction_id

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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.

    Optional:

    • client_transaction_id:String[40] Unique transaction id returned by the 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.

 

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 the 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 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 2 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. This will match the requested transaction type except when a Full Refund is converted to a Void automatically. (See the notes under Void / Capture / Refund Transactions)
     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 random and 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 Payment API 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).

 

Token Formatting

Token Type Data Type Prefix Suffix
Credit Card - One Time 16 Numeric Digits 1000 Last 4 digits from credit card
Credit Card - Multi Use 16 Numeric Digits 1100 Last 4 digits from credit card
eCheck - One Time 17 Numeric Digits 1000 Last 3 digits from bank account
eCheck - Multi Use 17 Numeric Digits 1100 Last 3 digits from bank account
Wallet 32 Hexadecimal (GUID) N/A N/A

 

Token Formatting Verification

All credit card and eCheck tokens make use of a modified Luhn algorithm to verify that the token number is formatted correctly. To check the format of an EpicPay Gateway token number, calculate the "check number" using the standard Luhn algorithm process. Then use "check number" % 10 == 1 rather than the standard "check number" % 10 == 0. The following JavaScript function will return true for any valid EpicPay Gateway credit card/eCheck token:

 

Example Token Verification Function (JavaScript)

console.log(checkToken("1000000000031111")) // Passes validation
console.log(checkToken("1000000000031112")) // Fails validation

function checkToken(value) {

  // Accept only digits
  if (/[^0-9]+/.test(value)) {
    return false;
  }

  var checkNumber = 0,
    nDigit = 0,
    bEven = false,
    n, cDigit;

  if (value.length < 16 || value.length > 17) {
    return false;
  }

  for (n = value.length - 1; n >= 0; n--) {
    cDigit = value.charAt(n);
    nDigit = parseInt(cDigit, 10);
    if (bEven) {
      if ((nDigit *= 2) > 9) {
        nDigit -= 9;
      }
    }

    checkNumber += nDigit;
    bEven = !bEven;
  }

  // Luhn algorithm modification; "checkNumber" modulo 10 == 1 rather than == 0
  return (checkNumber % 10) === 1;
}

 

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 Payment 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.

Register Multi-Use Token


For general information about Multi-Use Tokens, see: Tokenization Introduction.

This section explains how to generate a Multi-Use Token without placing a transaction. There are two API methods available to accomplish this: /RegisterToken and /RegisterTokenExt (an extended version, which returns additional information when tokenizing a credit card). Both accept the same request body and will return a token number when given valid payment information. When registering a credit card token, we will automatically process a $0 authorize transaction to verify that the card is valid.

Note: When using Multi-Use Tokens, the merchant is responsible for Credential On File (COF) compliance. Tokenization does not absolve them of this responsibility. For more information on COF, please consult the following external documents: Visa | Vantiv .

 

  • URL:

BaseURL/registertoken -OR- /registertokenext

NOTE: Endpoints are case-sensitive and must be in all lowercase.

 

Register Multi-Use Token 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 Object (Required if "method" is 'credit_card' or 'card_track').
bank_account Object The Bank Account Tokenization Object (Required if "method" is 'echeck').
token Object The One-Time Token Object (Required if "method" is 'card_token' or 'echeck_token').

 

Example Register Multi-Use Token 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 Register Multi-Use Token Request (Credit Card Swipe)

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

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

 

Example Register Multi-Use Token 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 Register Multi-Use Token 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 Register Multi-Use Token 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 Register Multi-Use Token Request (RegisterTokenExt - Credit Card)

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

{
  "method":"credit_card",
  "credit_card":{
    "card_number":"4484070000000000",
    "exp_month":"12",
    "exp_year":"2030"
  }
}

 

Example Register Multi-Use Token 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\"}"

 

Register Multi-Use Token Response Variables


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction. (See Appendix 2 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.
     card_info Object Returned only when using /RegisterTokenExt
       card_type String The credit card's network. (See Appendix 1 for a complete list of Card Types)
       country String The country in which the card was issued. ISO 3166-1 (2-digit version)
       international Boolean Indicates whether the card was issued internationally (from a US perspective)
       check_card Boolean Indicates whether the card is a check card.
       commercial Boolean Indicates whether the card is a commercial card.
       prepaid Boolean Indicates whether the card is a prepaid card (gift, HSA, etc.)

 

Example Register Multi-Use Token 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 Register Multi-Use Token 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": ""
  }
}

Example Register Multi-Use Token Response (RegisterTokenExt - Credit Card)

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

{
  "result": {
    "token": {
      "token_type": "epicpay",
      "token_number": "1100000024829424",
      "card_info": {
        "card_type": "discover",
        "country": "",
        "international": false,
        "check_card": false,
        "commercial": false,
        "prepaid": false
      }
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "001",
    "reason_text": "Received"
  }
}

Register One-Time Token


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 the EpicPay Gateway, 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.

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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 2 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

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

 

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 the EpicPay Gateway, as long as your application supports JavaScript. For more information, see One-Time Tokenization Library.

  • URL:

BaseURL/registeronetimetoken

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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 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] Credit Card or Bank Account Number. (Required if "method" is 'eCheck')
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] The bank account's 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 2 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

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

One-Time Tokenization Library


The EpicPay Gateway 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 Payment API. 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 Gateway Payment 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 bank 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 bank 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 Payment 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 single 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 customer_id is provided. When registering a credit card wallet item, we will automatically process a $0 authorize transaction to verify that the card is valid.

NOTE: When adding a wallet to a new customer, provide all of the customer's info and (optionally) a client_customer_id.

When adding a wallet to an existing customer, leave customer's info and client_customer_id blank and provide only the customer_id.

  • URL

BaseURL/addwalletitem

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    Conditionally Required:

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

    • customer_address:Object The Contact Object for the customer (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[40] An optional user-defined unique identifier that will be associated with the Customer. Provide this field only when creating a new customer.

    • billing_address:Object The Contact Object for the billing address.

 

Add Wallet Request Variables


Variable Description
method String The Payment Method.
customer_id String Fortis-defined unique identifier for a Customer (Required when adding a wallet item to an existing customer).
customer_address Object The Contact Object for the customer (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. Provide this field only when creating a new customer.
billing_address Object (Optional) The Contact Object for the billing address.

 

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 (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

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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] Expiration month expressed as a two-digit number (Required if the wallet item is a credit card. Values: "01"-"12").

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

    Optional:

    • billing_address:Object The Contact Object for the billing address.  

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. Values: "01"-"12").
exp_year String[2-4] Expiration year expressed as a two or four-digit number (e.g. "23" or "2023"). (Required if the wallet item is a credit card).
billing_address Object (Optional) The Contact Object for the billing address.
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 Payment API. All requests to delete a Wallet Item must include the WalletID as part of the URL.

  • URL

    BaseURL/deletewalletitem/WalletID

NOTE: Endpoints are case-sensitive and must be in all lowercase.

 

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 2 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 Fortis-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 Fortis-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

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

 

Example Edit Wallet Response

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

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

 

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

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • customer_address:Object The Contact Object for the customer ("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 Contact Object for the customer ("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 Fortis-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 2 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 Fortis-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": ""
  }
}

Subscriptions


The EpicPay Gateway Payment API allows you to set up Subscriptions (i.e. 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 canceled, 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.

NOTE: When adding a subscription for a new customer, provide all applicable customer info and (optionally) a client_customer_id.

When adding a subscription to an existing customer, provide a wallet belonging to the customer. Leave the client_customer_id blank.

  • URL

BaseURL/addsubscription

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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[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[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[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').

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

    • customer_address:Object The Contact Object for the customer (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. Provide this field only when creating a subscription for a new 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 Contact Object for the billing address.

    • 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.
  • Canadian merchants must use the currency "CAD" when submitting eCheck transactions.
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 "seconary_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[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[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[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').
epic_token Object The Epic Token Object (Required if "method" is 'epic_token').
customer_address Object The Contact Object for the customer (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. Provide this field only when creating a subscription for a new 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 Contact Object for the billing address.
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": "someone@example.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": "someone@example.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": "someone@example.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

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • Method:

    POST

  • Authorization:

    Basic: API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

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

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

    • 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').

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

    • customer_address:Object The Contact Object for the customer (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[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[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[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 optional Contact Object for the billing address 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.
  • Canadian merchants must use the currency "CAD" when submitting eCheck transactions.
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[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[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[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').
epic_token: Object The Epic Token Object (Required if "method" is 'epic_token').
customer_address Object The Contact Object for the customer (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 Contact Object for the billing address.
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,
  "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": "someone@example.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": "someone@example.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

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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 Payment API. All requests to delete a Subscription must include the SubscriptionID as part of the URL.

  • URL

    BaseURL/deletesubscription/SubscriptionID

NOTE: Endpoints are case-sensitive and must be in all lowercase.

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 2 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 Fortis-defined unique identifier for a Customer.
     wallet_id String Fortis-defined unique identifier for the Wallet.
     subscription_id String Fortis-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').

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",
      "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.

NOTE: Endpoints are case-sensitive and must be in all lowercase.

  • 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 The status object. If the transaction is found, the data in this object will indicate the status of the transaction. If the transaction is not found (or there are other errors with GetTransaction request), the data in this object will provide information about the error, and the "result" object will not be present on the response payload.
   response_code String Processing status of the transaction. (See Appendix 2 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.
     network_transaction_id String The network-specific unique identifier for this transaction. This property is provided solely for merchants who store raw credit card data or multi-use tokens within their own system as well as merchants who manage their own scheduling of recurring payments, in order to facilitate COF compliance.
     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.
     amount Integer Payment amount in cents (Returned unmodified).
     secondary_amount Integer Secondary transaction amount in cents.
     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).
     client_order_id String[40] A client-defined value that can be used to internally identify the order. It could be a purchase order or invoice number.
     client_customer_id String[40] A client-defined value that can be used to internally identity the customer.
     method String The payment method (Returned unmodified).
     designation String The Unique Name of the designation used for the transaction, if applicable.
     is_donation Boolean Indicates if the transaction was submitted as a donation.
     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 Contact Object for the billing address (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,
      "secondary_amount": 0,
      "currency": "USD",
      "client_transaction_id": "AXB1233309",
      "client_order_id": "R21118602",
      "client_customer_id": "f445b49c3e14adf8d12595e797fb1a4",
      "transaction_id": "39420",
      "network_transaction_id": "767491598531254"
      "method": "Visa",
      "sec_code": "WEB",
      "entry_description": "ECToken",
      "authorization_number": "TEST",
      "avs_code": "Y",
      "cvv_code": "M",
      "designation": "MyDesignation",
      "is_donation": true,
      "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": {
        "cf_mycustomfield1": "123",
        "cf_mycustomfield2": "ABC"
      }
    }
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Event Management


The EpicPay Gateway's Event Management feature allows merchants and partners to receive notifications anytime a specific event occurs. 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 Gateway 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 2 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_type String The type of transaction performed.
     amount Integer Payment amount in cents (Returned unmodified).
     secondary_amount Integer Secondary transaction amount in cents.
     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).
     client_order_id String[40] A client-defined value that can be used to internally identify the order. It could be a purchase order or invoice number.
     client_customer_id String[40] A client-defined value that can be used to internally identity the customer.
     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.
     method String The payment method (Returned unmodified).
     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.)
     designation String The Unique Name of the designation used for the transaction, if applicable.
     is_donation Boolean Indicates if the transaction was submitted as a donation.
     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 Contact Object for the billing address (Returned unmodified).
     merchant Object The Merchant Object
     metadata Object The Metadata Object.

 

Payment Authorization Webhook Object


Example Payment Authorization Webhook Object

{
  "result": {
    "payment": {
      "transaction_type": "Sale",
      "amount": 111,
      "secondary_amount": 0,
      "currency": "USD",
      "client_transaction_id": "AXB1233309",
      "client_order_id": "R21118602",
      "client_customer_id": "f445b49c3e14adf8d12595e797fb1a4",
      "transaction_id": "39420",
      "network_transaction_id": "767491598531254",
      "method": "card_token",
      "authorization_number": "TEST",
      "avs_code": "Y",
      "cvv_code": "M",
      "designation": "MyDesignation",
      "is_donation": true,
      "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",
        "postal_code": "01803-3747",
        "country_code": "US",
        "email": "example@example.com",
        "phone": {
          "number": "555-555-1212",
          "type": "Mobile"
        }
      },
      "token": {
        "token_type": "epicpay",
        "token_number": "1100000025451111",
        "account_holder_name": "Bob Smith"
      },
      "merchant": {
        "merchant_id": "12345",
        "company_name": "Test Merchant",
        "address_line_1": "12345 Main St.",
        "address_line_2": "Suite 1000",
        "city": "Tacodowns",
        "state_province": "MA",
        "postal_code": "12203-1737",
        "country_code": "US",
        "email": "example@example.com",
        "phone_number": "555-555-1234",
        "terminal_name": "My Terminal",
        "terminal_id": "d0086724632b4bd39bf51da670c33816"
      },
      "metadata": {
        "cf_mycustomfield1": "123",
        "cf_mycustomfield2": "ABC"
      }
    }
  },
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  }
}

Payment Authorization Webhook Tester


3-D Secure

 

Introduction


The EpicPay Gateway provides support for merchants who want to benefit from enhanced fraud protection available via 3DSecure (Verified by Visa and MasterCard Secure Code). The EpicPay Gateway can receive and pass through 3DSecure Authentication data to the processor for greater security on every transaction.

Completing transactions in this manner requires merchants to have a relationship with a third party 3-D Secure provider capable of authenticating and encrypting payment information before sending it to the EpicPay Gateway.

The typical 3DS workflow will look like this:

  1. The Merchant's website or application makes a request out to a 3rd party 3DS authentication provider.
  2. The authentication provider send back a cryptogram to the merchant website/application in the response, if successful.
  3. The website or application takes the cryptogram and makes a Sale or Authorize request using the cryptogram in order to complete the transaction
  4. The EpicPay Gateway informs the website/application of the response.

This section provides guidance on how to perform 3DS transactions through our EpicPay Gateway Payment API.

 

Completing a Transaction


When a customer successfully initiates a transaction on your website or application using 3-D Secure, you will receive a cryptogram from your 3DS provider. To complete this transaction, you must submit a Sale or Authorize request to the EpicPay Gateway using the provided cryptogram and "credit_card" as the "method".

When submitting the Sale or Authorize request, ensure that:

  • The "method" is set to "credit_card".
  • Under the "credit_card" object:
    • The "card_number" is populated with either the credit card number or DPAN given by the 3DS provider.
    • The "authentication" object is populated:
      • The "cryptogram" contains the Base64 encoded cryptogram given by the 3DS provider.
      • The "authentication_id" contains the transaction ID given by the 3DS provider, if one is given. Some providers do not offer this, in which case it may be omitted.
      • The "eci_indicator" contains the code indicating the status of 3DS authentication prior to submitting to the EpicPay Gateway, which given by the 3DS provider upon initiating the transaction.
      • The "source" contains the source of the cryptogram (either "network_3ds_v1" or "apple_pay").

Example Sale or Authorize Payload using 3-D Secure

{
  "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",
    "authentication":{
      "cryptogram": {{Base64EncodedCryptogram==}},
      "authentication_id": "abc123",
      "eci_indicator": "05",
      "source": "network_3ds_v1"
    }
  },
  "billing_address":{
    "postal_code":"12345"
  }
}

Level II and Level III Processing


The EpicPay Gateway Payment API allows merchants to provide Level II & III data for commercial card transactions. Providing this additional invoice-level transaction data may provide interchange cost benefits to business-to-business merchants who cater to larger corporations, enterprise businesses, and government entities. EpicPay Gateway can support Level II & III data for Visa and MasterCard, and level II data is supported for American Express.

NOTE: Level II and Level III Processing is only available to merchants boarding to Worldpay (Vantiv).

 

API Request Requirements


Level II

To send a valid Level II transaction request, you will be required to provide the following data:

  • Merchant's Tax ID Number: Must be provided using the tax_id property of each tax_item object.

  • Tax Amount: Must be provided using the tax_amount property of a tax_item object.

  • Tax Rate: Must be provided using the tax_rate property of a tax_item object.

  • Additional Requirements:

    • For Visa: The transaction must be taxable, and the tax charged must be between 0.1% and 22% of the transaction amount.
    • For MasterCard: The transaction must be taxable, and the tax charged must be between 0.1% and 30% of the transaction amount.

Level III

To send a valid Level III transaction request, you will be required to provide all data required for Level II processing as well as these additional items:

  • Line Items for Order: Must be provided as an array of line_item objects using the line_items property of the order_details object. All properties of line_item object are required for Level III processing.

    • A list of applicable codes for unit_of_measure and commodity_code can be found in Appendix 1.
  • Additional Requirements:

    • For Mastercard:
      • Order Number: Must be provided using the order_number property of the order_details object.
      • NOTE: For MasterCard, the transaction must be placed using a corporate, business, or purchasing card.
    • For Visa:
      • Discount Amount for Order: Must be provided using the discount_amount property of the order_details object.
      • Shipping Amount for Order: Must be provided using the shipping_amount property of the order_details object.
      • Duty Amount for Order: Must be provided using the duty_amount property of the order_details object.
      • NOTE: For Visa, the transaction must be placed using a corporate or purchasing card.

 

Example Level 3 Transaction Request

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

{
    "amount": "140",
    "currency": "usd",
    "method": "credit_card",
    "transaction_type": "sale",
    "credit_card": {
        "card_number": "4111111111111111",
        "card_holder_name": "Bob Smith",
        "exp_month": "01",
        "exp_year": "2025",
        "cvv": "123"
    },
    "billing_address": {
        "postal_code": "12345"
    },
    "order_details":{
        "order_number":"123",
        "discount_amount":0,
        "shipping_amount":30,
        "duty_amount":0,
        "is_tax_exempt":"true",
        "ship_from_postal_code":"10000",
        "line_items":[
            {
                "description":"Ballpoint Pens",
                "commodity_code":"62080",
                "product_code":"abc123",
                "discount_amount":0,
                "total_amount":100,
                "quantity":10.0000,
                "unit_cost": 10,
                "unit_of_measure":"UN",
                "tax_items":[
                    {
                        "tax_type":"02",
                        "tax_id":"1234567890",
                        "tax_amount":5,
                        "tax_rate":8.7500
                    }
                ]
            }
        ]
    },
    "shipping_address":{
        "first_name":"Jane",
        "last_name":"Smith",
        "address_line_1":"123 Lane Street",
        "city":"Townsville",
        "state_province": "TX",
        "postal_code": "10000",
        "country_code": "US",
        "email":"jsmith@example.com",
        "phone":{
            "number":"1234567890",
            "type":"mobile"
        }
    }
}

Appendix 1 - Request Codes / Types


 

Transaction Types


 

This table lists all of the valid transaction_type values.

Value Description
"authorize" An Authorization will place hold on the cardholder's funds to cover the transaction amount but are not flagged for settlement. These transactions must be flagged for settlement using a transaction of type 'capture' in order to be sent to the processor. Authorizations typically remain active for three to seven business days.

(Not available for eCheck, eCheck_token, or eCheck_wallet Transactions)
"sale" A Sale both authorizes the funds to cover the transaction and immediately flags the transaction for settlement. All sales completed before the processor cutoff time are batched and sent to the processor.
  • Credit Card Sale (Authorize and Capture): A standard sale using credit card information.
  • ACH/EFT Debit / eCheck Sale: A sale using a bank account and routing number. Like a credit card sale, eCheck/ACH/EFT transactions are automatically flagged for settlement. Immediate authorization of funds is not available for eCheck/ACH/EFT.
"capture" 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.
  • Capture - Full: Flags the full amount of the original authorization for settlement.
  • Capture - Partial: Flags a specified amount that is less than the original authorization. This will cause the remainder of the original authorization amount to be reversed.
(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.
  • Credit Card Authorization Reversal: Reverses the full amount of an existing authorization. This alerts the cardholder's bank that the previously authorized funds can be released and made available again for use. These funds can no longer be captured for settlement for this transaction.
  • Credit Card Void - Sale: Removes a sale or captured transaction from the day's batch record prior to end-of-day settlement. If the transaction has already been settled, "credit" should be used instead.
  • Credit Card Void - Credit / Refund: Removes a credit (i.e. refund) from the day's batch record prior to end-of-day settlement.
  • Credit Card Void - Capture: Removes a capture from the day's batch record prior to end-of-day settlement.
  • ACH Void - Sale: Removes an ACH Debit / eCheck Sale from daily settlement. If the transaction has already been settled, "credit" should be used instead.
  • ACH Void - Credit / Refund: Removes an ACH / eCheck credit (i.e. refund) from daily settlement.
(Voids can only occur if the transaction has not been settled.)
"credit" Transactions of type 'credit' will reverse a previously settled transaction.
  • Credit Card Refund - Full: Returns the full amount of the original transaction to the cardholder.
  • Credit Card Refund - Partial: Returns a specified portion of the original transaction to the cardholder.
  • ACH Refund / Credit: Returns a specified amount to the customer's bank. This amount may be full or partial but cannot exceed the transaction's original amount.
("credit" cannot apply to transactions that have not been settled. Attempts to perform a Full Refund on a non-settled transaction will be automatically converted to a void, and Partial Refunds are disallowed.)

 

SEC Codes


NOTE: Canadian merchants must use the sec_code "PPD" for all ACH/EFT (eCheck) transactions.

This table 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.
TEL Telephone Initiated Entries
The receiver must have authorization verbiage read and captured on the recorded customer authorization. Additionally, the authorization must provide the receiver with the method to revoke his authorization by notifying the originator in the manner prescribed, and the time frame in which the revocation of the authorization must be provided.

 

Payment Methods


 

This table 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 for more details.

Payment Method Description
credit_card Credit Card (Non-Swipe)                   
card_track Swiped Credit Card
echeck eCheck (ACH)
epic_token Epic Token
third_party_token Tokenized data originating from Apple Pay or Google Pay.
(Note: Google Pay is not available on all platforms. Contact your Fortis Sales Representative for details.)

 

COF Processing Types


 

This table lists all of the valid "cof_processing_type" values.

Value Description
initial_recurring Indicates the first payment on newly stored credit card data where there is an associated recurring payment subscription.
initial_unscheduled Indicates the first payment on newly stored credit card data when there is no associated recurring payment subscription.
recurring Indicates a subsequent recurring payment using stored credit card data.
unscheduled_cardholder Indicates a subsequent non-recurring usage of stored credit card data when the cardholder authorized the use of the stored credit card data.
unscheduled_merchant Indicates a subsequent non-recurring usage of stored credit card data when the cardholder did not authorize the use of the stored credit card data.

 

Card Types


 

This appendix describes the values returned in the "card_type" field inside any "credit_card" object found in a response. It also represents the card networks supported by the EpicPay Gateway.

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

 

ECI Indicator Values


 

This table describes the values used to indicate the success of 3DS authentication by a 3rd-party authentication provider. Values "00", "01", and "02" are seen using MasterCard transactions, while "05", "06", and "07" are seen using Visa, American Express, Discover, Diner's Club or JCB.

Value Description
"00" 3DS authentication has either failed, or could not be attempted. (MasterCard only)
"01" 3DS authentication was attempted, but either failed or could not be completed. (MasterCard only)
"02" 3DS authentication was successful. (MasterCard only)
"05" 3DS authentication was successful.
"06" 3DS authentication was attempted, but either failed or could not be completed.
"07" 3DS authentication has either failed, or could not be attempted.

 

Tax Type


This table describes the type of tax to apply to line items for Level 2 and 3 processing

Value Description
"00" Unknown
"01" Federal/National Sales Tax
"02" State Sales Tax
"03" City Sales Tax
"04" Local Sales Tax
"05" Municipal Sales Tax
"06" Other Tax
"10" Value Added Tax (VAT)
"11" Goods and Services Tax (GST)
"12" Provincial Sales Tax (PST)
"13" Harmonized Sales Tax (HST)
"14" Quebec Sales Tax (QST)
"20" Room Tax
"21" Occupancy Tax
"22" Energy Tax

 

Units of Measure


 

Commodity Codes


Appendix 2 - Response Codes / Types


 

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.

 

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.
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> (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 <healthcareIIAS> 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 Hard Decline There is an internal problem with the system.
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
E33 Invalid Request: Target Transaction was charged back or rejected
E34 Invalid Request: Target Transaction is voided or not approved
E35 Invalid Request: Target Transaction can no longer be voided
E36 Invalid Request: Cannot refund the Target Transaction. Please void it and then run a new Transaction for the intended amount.
E37 Invalid Third Party Token.
E38 Third Party Token Type not supported by merchant.
E39 Valid email address is required when email_receipt is true.
E40 (Property) Exceeds Max Length: (xx)
E97 Invalid Request: Processor Error
E98 Invalid Request: Validation Error
E99 Invalid Request: Unknown Error

 

ACH Return Reason Codes


 

This table contains a list of ACH Return Reason Codes, which can apply to either eCheck (ACH/EFT) transactions, or Dynamic Payout funding instructions.

NOTE: If an eCheck is returned for reason Code R01 or R09, it is eligible for redeposit. Codes are not case sensitive; use a case insensitive comparison to handle response values (i.e. code should be written in a way that will interpret "r01" and "R01" as identical values).

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.

 

ACH Notice of Change (NoC) Reason Codes


 

This table contains a list of ACH NoC Change Codes.

NOTE: Codes are not case sensitive; use a case insensitive comparison to handle response values (i.e. code should be written in a way that will interpret "c01" and "C01" as identical values).

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).

 

Transaction Response Codes


 

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

NOTE: Codes are not case sensitive; use a case insensitive comparison to handle response values (i.e. code should be written in a way that will interpret "Received" and "received" as identical values).

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 - Reason Codes 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 encounters a communication or network error. See Appendix 2 - Reason Codes for more details on reason code and reason text.

 

Authentication Response Values


 

The values in this table describe the success of 3DS authentication after the transaction is submitted to the processor.

Value Description
"unspecified" Unspecified
"passed" Passed
"passed_no_liability_shift" Passed without liability shift (e.g. The ECI value is incorrect or the card type is excluded)
"failed" Failed
"invalid_data" Not Verified - Invalid security data (e.g. cryptogram is malformed or missing.)
"no_issuer_support" Not Verified - Issuer not participating
"error" Not Verified - Unspecified reason

Appendix 3 - Request / Response Objects


 

Payment Method Objects


Some API Methods require a Payment Method Object. These tables show the structure of each Payment Method Object. These objects are also returned during Get Transaction and Payment Authorization Webhooks where applicable and with sensitive fields masked (account number, card number) or removed (expiration month & year, CVV).

 

Credit Card Object


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

Property Description
card_number String (Required) Credit card number or DPAN.
card_holder_name String[50] (Required) Cardholder's name.
exp_month String (Required) Expiration month. (Values: "01"-"12")
exp_year String[2-4] (Required) Expiration year expressed as a two or four-digit number (e.g. "23" or "2023")
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.
authentication Object (Optional) The Authentication Object. Use this object to provide any relevant data when making a 3-D Secure enabled transaction. This may also be used to provide cryptogram data if the transaction has been authenticated through an Apple Pay or Google Pay workflow.
    -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.
  • For U.S. merchants, must be a valid U.S. bank routing number and must pass Mod 10 validation check.
  • For Canadian merchants, must represent a valid Canadian bank, formatted as:
    • Leading 0 + three-digit Institution Number + five-digit Transit (Branch) Number
account_number String[17] Bank account number.
account_holder_name String[50] Bank account holder's name.

 

Wallet Object


Returned during a Sale or Authorize response when token_type is "wallet".

Property Description
wallet_id String Wallet ID

 

Payment Token Object


Returned during a Sale or Authorize response when "token_type" 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] Account holder's name.

 

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', 'google_pay', 'apple_pay')
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.
When using 'google_pay' or 'apple_pay', see 3rd Party Tokenization.
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. (Values: "01"-"12")
exp_year String (Required when "token_type" is 'card_token') Expiration year expressed as a two or four-digit number (e.g. "23" or "2023")
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.

 

Contact Info Objects


Some API Methods allow or require contact information to be provided. These tables show the structure of each of Contact Info object.

 

Contact 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] Contact's first name.
last_name String[20] Contact's last name.
company_name String[50] Contact's company name.
address_line_1 String[100] Contact's address line 1.
address_line_2 String[20] Contact's address line 2.
city String[50] Contact's city.
state_province String[50] Contact's state or province.
postal_code String[10] Contact's postal code.
  • When Contact's country_code is "US", must be a U.S. Zip or Zip+4.
  • When Contact's country_code is "CA", must be a Canadian postal code.
country_code String[2] Contact's country code. (Default: 'US')
email String[256] Contact's email address.
phone Object Contact'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.
  • When Merchant's country_code is "US", must be a U.S. Zip or Zip+4.
  • When Merchant's country_code is "CA", must be a Canadian 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.

 

Level II & Level III Objects


These tables detail objects that are used with Level II and Level III transactions.

 

Order Details Object


Property Description
order_number String[17] A reference ID used by the customer for the purchase (i.e. Purchase Order Number). (Required for MasterCard Level III transactions.)
discount_amount Integer The amount of discount for the order. Two decimal places are implied (e.g. 500 = $5.00). (Required for Visa Level III transactions.)
shipping_amount Integer The shipping cost for the order. Two decimal places are implied (e.g. 500 = $5.00). (Required for Visa Level III transactions.)
duty_amount Integer The duty on the total purchased amount for the order. Two decimal places are implied (e.g. 500 = $5.00). (Required for Visa Level III transactions.)
is_tax_exempt String[5] Indicates whether the transaction is exempt from sales tax. Must set to true if the sales tax is zero. (Values: "true", "false", "yes", "no")
ship_from_postal_code String[10] The postal code from which the product ships.
line_items List A list of Line Item objects, each containing line item details for the order. At least one line item with amount, description, and quantity required for Level III qualification.
tax_items List A list of Tax Item objects, each containing tax details for the order. A minimum of one item (either at this level or the line_item level) is required to receive the best interchange rate for Level II and Level III corporate purchase.
invoice_number String[15] (Optional) The merchant's invoice number. If you do not know the invoice number, do not include this property.
order_date String[10] (Optional) The date the order was placed. (Format in ISO-8601 i.e. "yyyy-MM-dd")

 

Line Item Object


NOTE: All properties are required for Level III transactions.

Property Description
description String[26] A brief text description of the purchased item.
commodity_code String[12] The identifier assigned by the card acceptor to categorize the purchased item. (See: Commodity Codes)
product_code String[12] This value is a merchant-defined description code of the product/service. This could be an inventory number, UPC, catalog number, or some other value that the merchant uses to define the specific product.
discount_amount Integer The amount of discount for the item. Two decimal places are implied (e.g. 500 = $5.00).
total_amount Integer The total cost of the line items purchased, not including tax. For example, if the order was for 5 pencils at $1.00 each, the total would be 500. Two decimal places are implied (e.g. 500 = $5.00).
quantity Decimal(9,4) The quantity of the item purchased. (e.g. 12345.1234)
unit_cost Integer The cost per unit of the item purchased. Four decimal places are implied (e.g. 500 = $5.00).
unit_of_measure String[3] The EpicPay Gateway Code for the unit of measure that describes the purchased item. (See: Units of Measure)
tax_items List A list of Tax Item objects, each containing tax details for this line item. Minimum of one item (either at this level or the parent level) is required to receive the best interchange rate for Level II and Level III corporate purchase.

 

Tax Item Object


Property Description
tax_type String[2] The tax type applied to the order (or, if applied at the line_item level, this value should indicate the tax rate applied to the line item).
tax_id String[12] The Merchant's Tax ID number. (Required for Level II transactions.)
tax_amount Integer The total amount of tax applied for the order (or, if applied at the line_item level, this value should indicate the total tax applied to the line item). Two decimal places are implied (e.g. 500 = $5.00). (Required for Level II transactions.)
tax_rate Decimal(5,4) The tax rate that applies to the order (or, if applied at the line_item level, this value should indicate the tax rate applied to the line item) (e.g. 8.7500 = 8.75% ).

 

Authentication Object


Property Description
cryptogram String The Base 64 encoded cryptogram given by the authentication provider.
authentication_id String A transaction ID given by the authentication provider. Some providers do not supply this property, in which case, this property may be omitted. (Note: This may be called XID by some providers.)
eci_indicator String Indicates whether the transaction has been authenticated through a third-party workflow. Potential values are listed in the ECI Indicator Values table.
source String Indicates the source of the cryptogram. (Values: "network_3ds_v1", "apple_pay", "google_pay")

Metadata Object


 

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

 

Property Description
cf_{{Unique_Name}} String Represents a custom field entered on a Hosted Page. Each custom field key is prefixed with "cf_", followed by its Unique Name (configurable through Hosted Pages in the VT) in all lowercase. If there are multiple custom fields for a transaction, they will each appear as a separate key-value pair under the metadata object. Active and Disabled custom fields applicable to the transaction will appear, but Deleted ones will not.

 

Authentication Object


Property Description
cryptogram String The Base 64 encoded cryptogram given by the authentication provider.
authentication_id String A transaction ID given by the authentication provider. Some providers do not supply this property, in which case, this property may be omitted. (Note: This may be called XID by some providers.)
eci_indicator String Indicates whether the transaction has been authenticated through a third-party workflow. Potential values are listed in the ECI Indicator Values table.
source String Indicates the source of the cryptogram. (Values: "network_3ds_v1", "apple_pay")

 

Payment API Version History


Note: All updates are backwards-compatable.

Version Revision Date Description
1.41.0 2/15/2022 Introduced support for placing EFT (ECheck) transactions by Canadian merchants.
1.40.1 9/28/2021 Fixed Billing Address issue when placing Sale/Auth transactions using a Wallet.
1.39.0 6/28/2021 Internal improvements.
1.38.0 6/14/2021 For data privacy and security, values provided in non-account fields that look like account or social security numbers will be automatically masked. Added validation to the Contact's postal_code property.
1.37.0 5/19/2021 Added client_order_id and client_customer_id to the response payload when using Get Transaction.
1.36.0 4/27/2021 Internal improvements.
1.35.0 4/05/2021 Internal improvements.
1.34.2 12/14/2020 Added support for 3D Secure, Level II and Level III transactions. To reduce costs and risk to merchants and integrators, we have updated how refunds work: when refunding an unsettled transaction, full refunds will be converted to voids automatically, while partial refunds will be denied.
1.33.0 11/30/2020 Internal improvements to iframe messaging for Hosted Checkout. Documentation updated with warnings for all endpoints to be in lowercase.
1.32.0 10/15/2020 Internal improvements. Documentation updated to recommend utilizing epic_token for wallets and tokens where applicable.
1.31.0 9/30/2020 Internal improvements to improve stability.
1.30.1 8/24/2020 Added email_receipt property to Authorize request.
1.29.0 7/27/2020 Internal improvements for RapidConnect support.
1.28.0 7/23/2020 Added network_transaction_id, donation, and designation properties to GetTransaction response.
1.27.0 7/13/2020 Internal improvements related to transaction amount.
1.26.1 6/26/2020 Improved validation for transaction amount properties.
1.25.0 6/12/2020 Added support for epic_token on subscription requests. Various internal bug fixes.
1.24.0 5/19/2020 Added custom fields within the metadata object to GetTransaction Response.
1.23.1 4/23/2020 Various bug fixes and refactoring.
1.22.2 3/05/2020 Added Credential On File flags for Sale/Authorize.
1.21.3 12/20/2019 Added the "RegisterTokenExt" method under the Register Multi-Use Token section.
1.20.1 9/05/2019 Added sec_code and entry_description for eCheck subscriptions. Both are also visible using Get Transaction.
1.18.4 8/28/2019 Added Appendix 12 that details transaction response codes.
1.18.3 8/09/2019 Added the metadata object to the GetTransaction response.
1.17.5 6/26/2019 Added is_test parameter to Sale/Authorize Transaction documentation. Improved descriptions for SEC codes.
1.12.6 6/07/2018 Added validation to restrict allowed characters in the Client Identifier fields.
1.12.2 5/04/2018 Added two new methods for activating and deactivating recurring payment subscriptions.
1.12.1 7/03/2017 The nonspecific "Database Error" responses for field length violations have been improved to show scenario-specific error messages.
1.11.4 5/17/2017 Improved the "Reason Text" for various invalid request scenarios.
1.11.3 4/21/2017 The "One-Time-Tokenization Library" was updated to support callback methods.
1.11.2 4/17/2017 The "RegisterToken" method was modified to allow generation of a Multi-Use token using a One-Time-Use token.
1.11.1 4/12/2017 Added new read-only method: GetTransaction.
1.10.2 2/21/2017 Added support for Create / Read / Update of Recurring Payments and Wallets.
1.8.2 2/14/2017 Added support for Card Swipe.