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/

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.

• URL

  BaseURL/authorize

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

  • amount:Integer Transaction amount in cents.

  • currency:String[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

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.

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:

• Google Pay Web Developer Documentation
• Google Pay Web Integration Checklist
• Google Pay Web Brand Guidelines

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

• Google Pay Android Developer Documentation
• Google Pay Android Integration Checklist
• Google Pay Android Brand Guidelines

Transaction Sale / Authorize Response

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

Payment Response Variables for Sale / Authorize

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.

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

• URL

  BaseURL/authorize/transaction_id

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

  • amount:Integer Transaction amount in cents.

  • transaction_type:String The Type of Transaction to perform.

  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

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

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

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

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

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

  Conditionally Required:

  • credit_card:Object The Credit Card Tokenization Object (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').

Register Multi-Use Token Request Variables

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

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.

• Note: Part 2 can be automated using the One-Time-Use Token Library (although some initial configuration is required).

Part 1 - JWT Token Request

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

• URL:

  BaseURL/requestjwt

• Method:

  POST

• Authorization:

  Basic

API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

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

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

JWT Token Request Variables

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

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

• 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

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

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.

• Single Input Field for Bank Account Number and Credit Card Number:

  • Demo 1 - Data-Attributes Method
  • Demo 2 - Mapping Method

• Two Separate Input Fields for Bank Account Number and Credit Card Number:

  • Demo 3 - Data-Attributes Method
  • Demo 4 - Mapping Method

• Using Post Tokenization Callbacks:

  • Demo 5 - Data-Attributes Method
  • Demo 6 - Mapping Method

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.

• Sandbox Library Path: https://sandbox-api.epicpay.com/payment/v1/scripts/EpicTokenize.min.js

• Production Library Path: https://api.epicpay.com/payment/v1/scripts/EpicTokenize.min.js

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:

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:

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.

• URL

BaseURL/addwalletitem

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

  • method:String The Payment Method.

  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

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.

• URL

  BaseURL/editwalletitem/WalletID

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

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

  Conditionally Required:

  • exp_month:String[2] 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

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

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

Delete Wallet Request Variables

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

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

• 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

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

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.

Add a Subscription:

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

• URL

BaseURL/addsubscription

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

  • amount:Integer Transaction amount in cents.

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

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

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

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

  Conditionally Required:

  • period:Integer[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

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

• 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

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

• 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

Suspend Subscription Response Variables

Example Suspend Subscription Request

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

Example Suspend Subscription Response

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

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

Example Suspend Subscription Curl

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

Unsuspend a Subscription:

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

• URL

  BaseURL/subscription/unsuspend/SubscriptionID

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

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

Unsuspend Subscription Request Variables

Suspend Subscription Response Variables

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

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json  

Delete Subscription Request Variables

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

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.

• URL

  BaseURL/gettransaction/id

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

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

Get Transaction Request Variables

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

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

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.

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.

SEC Codes

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

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.

COF Processing Types

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

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.

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.

Tax Type

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

Units of Measure

• Units of Measure (.xlsx) - A list of available units of measure for Level II, III transactions.

Commodity Codes

• Commodity Codes (.pdf) - A list of all available commodity codes, grouped by subclass.

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.

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.

Reason Codes

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

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

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

Authentication Response Values

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

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

Bank Account Object

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

Wallet Object

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

Payment Token Object

Returned during a Sale or Authorize response when "token_type" is 'card_token' or 'echeck_token'.

Epic Token Object

Use this if "method" is 'epic_token'.

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

Phone Object

Merchant Object

Level II & Level III Objects

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

Order Details Object

Line Item Object

NOTE: All properties are required for Level III transactions.

Tax Item Object

Authentication Object

Metadata Object

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

Authentication Object

Payment API Version History

Note: All updates are backwards-compatable.