Boarding API


 

Introduction


The EpicPay Gateway Agent API is a web service that allows EpicPay agents to run reports as well as migrate their merchant data to the EpicPay Gateway. This process greatly simplifies the merchant boarding process. When this web service is used to migrate merchant data to EpicPay, the merchant will have access to an application that is pre-filled with much of the necessary information. See the Merchant Boarding method for more information.

The EpicPay Gateway Agent 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 Agent API.

 

BaseURL

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

 

API Keys

These credentials will be different from the Payment API credentials. Please contact EpicPay to get your Agent API credentials.


Note: All requests must be made over TLS/SSL.

Authentication


To use the EpicPay Gateway Agent API, you will need to provide your merchant boarding credentials. They are:

  • API Key ID: This value identifies the agent under which the merchant will be boarded.
  • Password: Authenticates the EpicPay Agent API request. This value should not be exposed to the public.

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

Merchant Boarding


This method can be used to pre-populate data on the Merchant Processing Application (MPA), a form that prospective merchants must complete and sign prior to approval. Using this method will reduce the effort required by the merchant at boarding time, in scenarios where data about the prospective merchant has already been collected. This method will return an Application ID, which can be sent to a prospective merchant to obtain and complete the pre-filled application.

 

Properties that are marked "Required" indicate the minimum required data for creating and saving an MPA. When using this method, you must provide data for each "Required" property, or you will not receive an Application ID. Properties that are marked "Required for completion" are those which need to be provided to EpicPay before the Merchant Processing Application can be approved. These properties may be omitted or left blank when using this method, however, the merchant will be required to provide this data before the application can be submitted. Properties that are marked "Conditionally Required" may be required for completion of the Merchant Processing Application, depending on the values provided for other fields. See the description for each of these properties for more information about their requirement criteria.

 

Note: Template_id is one of the required fields. This field is provided by EpicPay and requires pre-configuration. It also allows for pre-configuring of the API fields business_category, business_type, business_description, swiped_percent, keyed_percent, and ecommerce_percent. Any of those pre-configured values, if configured, can be overwritten by calling the same fields in the API.

Board a Merchant:

Use this method to board a merchant to the EpicPay Gateway.

  • URL

BaseURL/BoardMerchant

  • Method:

    POST

  • Authorization:

    Basic:

API Key ID : Password

  • Headers:

    • Content-Type: application/json
  • Data:

    Required:

    • email: String Merchant email address.

    • dba_name: String Merchant "Doing Business As" name.

    • template_id String The ID of the template to be used - this value will be provided by EpicPay.

    • location: Object The Location Object.

      • phone_number String Merchant's business phone number.
    • primary_principal Object The Primary Principal Object.

      • first_name String Primary principal or signer's first name.
      • last_name String Primary principal or signer's last name.
    • app_delivery String The delivery method of the app to the merchant. See App delivery.

    Conditionally Required:

    • website: String Merchant's business website (Required if "ecommerce_percent" is greater than 0).

    • business_category: String The Category of the merchant's business (Required if "business_type" is provided). Note: "business_type" must belong to the appropriate "business_category" as detailed in Appendix 7.

    Required for Completion:

    • ownership_type: String The Ownership Type of the merchant's business.

    • fed_tax_id: String Federal Tax ID (EIN).

    • cc_average_ticket_range: Integer Average Transaction Amount Range (Applicable when Template Application Type is 'credit_card' or 'both').

    • cc_monthly_volume_range: Integer Monthly Processing Volume Range (Applicable when Template Application Type is 'credit_card' or 'both').

    • cc_high_ticket: Integer Highest transaction amount in dollars (Applicable when Template Application Type is 'credit_card' or 'both').

    • ec_average_ticket_range: Integer Average Transaction Amount Range (Applicable when Template Application Type is 'echeck' or 'both').

    • ec_monthly_volume_range: Integer Monthly Processing Volume Range (Applicable when Template Application Type is 'echeck' or 'both').

    • ec_high_ticket: Integer Highest transaction amount in dollars (Applicable when Template Application Type is 'echeck' or 'both').

    • business_type: String The Type of a merchant's business.

    • business_description: String Description of Goods or Services.

    • swiped_percent: Integer Card present/swiped percentage.

    • keyed_percent: Integer Card not present/keyed percentage.

    • ecommerce_percent Integer eCommerce percentage.

    • bank_account Object The Bank Account Object.

      Note: The sum total of "swiped_percent", "keyed_percent" and "ecommerce_percent" must add up to 100.

    Optional:

    • legal_name: String Merchant legal name (leave blank if same as DBA name).

    • contact Object The Contact Object.

    • client_app_id String Client-Issued ID to uniquely identify the merchant.

    • app_complete_endpoint String _Client-side redirect URL called after merchant completes application.

    • alt_bank_account Object The Alternate Bank Account Object.

    • is_test String For testing only. When this property is set to "true", the application will be submitted in demo mode. (Values: 'true', 'false'; Default: 'false')

     

Boarding Request Variables


Variable Description
primary_principal Object The Primary Principal Object.
template_id Integer[10] The ID of the template to be used - this value will be provided by EpicPay.
email String[100] Merchant email address.
dba_name String[100] Merchant "Doing Business As" name.
location Object The Location Object.
app_delivery String[12] The delivery method of the app to the merchant. See App delivery.
business_category String[50] The Category of the merchant's business (Required if "business_type" is provided). Note: "business_type" must belong to the appropriate "business_category" as detailed in Appendix 7.
business_type String[50] The Type of a merchant's business.
business_description String[200] Description of Goods or Services.
swiped_percent Integer[3] Card present/swiped percentage (values: 0-100).
keyed_percent Integer[3] Card not present/keyed percentage (values: 0-100).
ecommerce_percent Integer[3] eCommerce percentage (values: 0-100).
ownership_type String[10] The Ownership Type of the merchant's business.
fed_tax_id String[10] Federal Tax ID (EIN).
cc_average_ticket_range Integer[2] Average Transaction Amount Range (Applicable when Template Application Type is 'credit_card' or 'both').
cc_monthly_volume_range Integer[2] Monthly Processing Volume Range (Applicable when Template Application Type is 'credit_card' or 'both').
cc_high_ticket Integer (range: 0-30000) Highest transaction amount rounded to the next dollar (No decimal and applicable when Template Application Type is 'credit_card' or 'both').
ec_average_ticket_range Integer[2] Average Transaction Amount Range (Applicable when Template Application Type is 'echeck' or 'both').
ec_monthly_volume_range Integer[2] Monthly Processing Volume Range (Applicable when Template Application Type is 'echeck' or 'both').
ec_high_ticket Integer (range: 0-30000) Highest transaction amount rounded to the next dollar (No decimal and applicable when Template Application Type is 'echeck' or 'both').
website String[100]Merchant's business website (Required if "ecommerce_percent" is greater than 0).
bank_account Object (Optional) The Bank Account Object.
legal_name String[100] (Optional) Merchant legal name (leave blank if same as DBA name).
contact Object (Optional) The Contact Object.
client_app_id String[50] (Optional) Client-Issued ID to uniquely identify the merchant (Returned unmodified).
app_complete_endpoint String[400] (Optional) Client-side Redirect URL called after merchant completes application.
alt_bank_account Object (Optional) Secondary Account used.
is_test String (Optional) For testing only. When this property is set to "true", the application will be submitted in demo mode. (Values: 'true', 'false'; Default: 'false')

Note: The sum total of "swiped_percent", "keyed_percent" and "ecommerce_percent" must add up to 100.

 

Example Boarding Request

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

{
  "client_app_id": "12345",
  "email": "totalhome@example.com",
  "dba_name": "Discount Home Goods",
  "legal_name": "Total Home Goods, LLP.",
  "ownership_type": "llp",
  "fed_tax_id": "00-0000000",
  "location": {
    "address_line_1": "1200 West Hartford Pkwy.",
    "address_line_2": "Suite 2000",
    "city": "Dover",
    "state_province": "DE",
    "postal_code": "55022",
    "phone_number": "555-555-1212"
   },
  "website": "http://www.example.com",
  "cc_average_ticket_range": 5,
  "cc_monthly_volume_range": 1,
  "cc_high_ticket": 1500,
  "ec_average_ticket_range": 5,
  "ec_monthly_volume_range": 2,
  "ec_high_ticket": 1500,
  "business_category": "education",
  "business_type": "school",
  "business_description": "School",
  "swiped_percent": 0,
  "keyed_percent": 0,
  "ecommerce_percent": 100,
  "primary_principal": {
    "first_name": "Bob",
    "last_name": "Fairview",
    "middle_name": "Nathaniel",
    "title": "Dr.",
    "address_line_1": "1354 Oak St.",
    "address_line_2": "Unit 203",
    "city": "Dover",
    "state_province": "DE",
    "postal_code": "55022",
    "phone_number": "555-555-1234",
    "date_of_birth": "2017-06-05",
    "ssn": "1234",
    "ownership_percent": 100
   },
  "contact": {
    "first_name": "Jeffery",
    "last_name": "Todd",
    "phone_number": "555-555-3456",
    "email": "jtodd@example.com"
   },
  "bank_account": {
    "account_holder_name": "Bob Fairview",
    "routing_number": "011103093",
    "account_number": "01234567890123"
   },
  "alt_bank_account": {
    "account_holder_name": "Bob Fairview",
    "routing_number": "011103093",
    "account_number": "01234567890124",
    "deposit_type":"fees_only"
   },
  "template_id": 7564,
  "app_complete_endpoint":"http://www.example.com"
}

 

Boarding Response

 

Boarding Response Variables


Variable Description
status Object Status of the API Request.
  response_code String Status of the boarding request. See Appendix 13 for a complete list of response codes. (values: "Received", "Error")
  reason_code String Returns a reason code if there is an error with the request. Otherwise, returns empty (""). See Appendix 4 for a complete list of reason codes.
  reason_text String A message that accompanies the "reason_code".
result Object Not available when the response code is 'Error'.
  app_link String[400] A full page or iframeable link, set in the request app_delivery field, that can be used to retrieve and resume the generated merchant application. No link will be returned for the Default.
  epic_app_id String[128] EpicPay internal ID. Can be created that can be used to uniquely reference an application if a client_app_id is not supplied.
  client_app_id String[20] Optional unique ID generated on the client to distinctly identify an application. Enforcement of uniqueness must be performed on the client. (Returned unmodified).
  dba_name String[100] Merchant "Doing Business As" name. (Returned unmodified).
  email String[100] Merchant email address (Returned unmodified).
  app_delivery String[20] The app delivery method to the Merchant. See app_delivery (Returned unmodified).

 

Example Boarding Response

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

{
  "result": {
    "app_link": "https://mpa.epicpay.com/ezapp/signup/7271bd8180684862928555caf201f156",
    "epic_app_id": "7271bd8180684862928555caf201f156",
    "client_app_id": "ABC123",
    "dba_name": "Discount Home Goods",
    "email": "totalhome@example.com",
    "app_delivery": "link_full_page"
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Merchant Application


Using the MPA iframe

 

To generate an iframe-ready MPA link, use the Board a Merchant API method with "app_delivery" set to "link_iframe".

EpicPay partners may elect to present the MPA to a prospective merchant through an iframe: a seamless way of integrating the application onto the partner's website. The application is designed to accept custom styling to fit the partner's needs. For more information, contact your EpicPay relationship manager to discuss whitelabel options.

Hosting the iframe on your website is easy. Simply add an iframe element to your website and set the src attribute equal to the app_link generated by the Boarding API. Inline styling may be added to the iframe element itself, but it will not affect the application page it hosts. The following code snippet is a basic implementation of an iframe:

 

<iframe src="{app_link}"></iframe>

 

Events

 

The MPA iframe will post messages to the page hosting it (the parent page). This allows the parent page to listen to events happening within the iframe in a safe and secure manner, and perform actions accordingly. In order to take advantage of this feature, the parent page must have an event listener that can receive and read posted messages from the iframe. For more information, see this page on the Mozilla Dev Docs: Window.postMessage() . The message format is in JSON. To see a demonstration of an event listener, see the Live Demo section below.

 

Live Demo

The following demo webpage is built to show how an event listener can be used to receive and act upon messages posted by an iframe. It hosts an iframed application that posts messages to its parent (the demo page, in this case) in the same manner the MPA would. The demo page will then display a message and scroll itself based on the output of the iframe. The demo also has an option to display the JavaScript code used to drive itself.

Click here to see it in action.

 

iframe Message Variables


Variable Description
EpicIFrame Object Root object for all messages.
  loaded Boolean Returned when the iframe finishes loading (values: true)
  modal Object Returned when the signer clicks "Verify Info" to submit the merchant information for verification.
    reason String Indicates the result of merchant information verification (values: "agreement", "info", "error").
"agreement": The merchant information has passed verification, and the MPA advances to the Terms of Service agreement.
"info": The user has opened an information popup (i.e. "See Rate Detail").
"error": The merchant information has failed verification.
  submitted Object Returned when the signer clicks "I Agree" to complete the application.
    status String Indicates the status of the application upon submission (values: "approved", "pending", "error").
"approved": The application was successful and has been automatically approved.
"pending": The application was submitted and is pending review for approval.
"error": An internal error has been hit.
  resize Object Returned whenever the size of the iframe's viewport changes.
    height Integer Indicates the current height of the iframe in pixels.

Example iframe Message

{
    "EpicIFrame": {
        "modal": {
            "reason": "agreement"
        }
    }
}

Webhooks

 

Introduction


EpicPay partners can opt to receive a webhook whenever one of their merchant applications is pended, approved, or declined by EpicPay. For example, the agent would receive one webhook messages if a merchant is immediately approved, or two webhooks if they were pended and then subsequently approved after review. Partners may also opt to receive the Extended Merchant Approval payload in place of the standard approval payload, which includes the boarded merchant's information. The format for this webhook is JSON. NOTE: Please ensure 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 responses 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. To configure a single endpoint for all responses (and optionally provide us with your Basic Authentication credentials), contact your Account Manager.

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

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

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

 

Merchant Approval Webhook Object


Variable Description
result Object Result Object. (Not available when the response code is 'error'.)
   gateway_credential Object Contains the gateway credentials for the merchant.
     epic_id String Unique identifier for the merchant.
     gateway_id String Unique identifier for the merchant's terminal.
     client_app_id String Optional client-issued unique identifier for an application. Enforcement of uniqueness must be performed by the client. (Returned unmodified).
     epic_app_id String EpicPay internal ID. Can be used to uniquely reference an application if a client_app_id is not supplied.
     api_key_id String Basic Authentication Username for merchant's Payment API access.
     api_key_password String Basic Authentication Password for merchant's Payment API access.
status Object Status of the API Request.
   response_code String Processing status of the application. See Appendix 13 for a complete list of response codes. (values: "pended", "approved", "declined")
   reason_code String Currently unused.
   reason_text String A message that accompanies the reason_code.

 

Merchant Pended Webhook Object


Variable Description
result Object Result Object. (Not available when the response code is 'error'.)
   merchant_info Object Contains the merchant's application information.
     client_app_id String Optional client-issued unique identifier for an application. Enforcement of uniqueness must be performed by the client. (Returned unmodified).
     epic_add_id String EpicPay internal ID. Can be used to uniquely reference an application if a client_app_id is not supplied.
     epic_id String Unique identifier for the merchant.
     dba_name String DBA name of the merchant. Matches the legal name if not provided.
     email String Primary email associated with the merchant.
status Object Status of the API Request.
   response_code String Processing status of the application. (See Appendix 13 for a complete list of Response Codes)
   reason_code String Currently unused.
   reason_text String A message that accompanies the reason_code.

 

Extended Merchant Approval Webhook Object


Variable Description
result Object Result Object. (Not available when the response code is 'error'.)
   gateway_credential Object Contains the gateway credentials for the merchant.
     epic_id String Unique identifier for the merchant.
     gateway_id String Unique identifier for the merchant's terminal.
     client_app_id String Optional client-issued unique identifier for an application. Enforcement of uniqueness must be performed by the client. (Returned unmodified).
     epic_app_id String EpicPay internal ID. Can be used to uniquely reference an application if a client_app_id is not supplied.
     api_key_id String Basic Authentication Username for merchant's Payment API access.
     api_key_password String Basic Authentication Password for merchant's Payment API access.
   merchant_info Object Contains the merchant's application information.
     legal_name String Legal name of the merchant.
     website String Website associated with the merchant.
     business_type String The business type that best describes the merchant. (See Business Categories and Business Types)
     business_category String The business category that best describes the merchant. (See Business Categories and Business Types)
     business_description String User-entered description of the business entered during the application.
     ownership_type String The type of ownership in which the business is registered. (See Ownership Types)
     fed_tax_id String Federal tax ID. Returns with first 5 digits masked.
     is_test String Indicates whether the application was launched in demo mode. (Values: 'true', 'false'; Default: 'false')
     location Object The Location Object.
     primary_principal Object The Primary Principal Object.
     bank_account Object The Bank Account Object.
     cc_monthly_volume_range String Expected monthly volume range through credit card. (See Monthly Volume Ranges)
     cc_average_ticket_range String Expected average ticket range through credit card. (See Average Ticket Ranges)
     cc_high_ticket Int Expected maximum ticket through credit card.
     ec_monthly_volume_range String Expected monthly volume range through eCheck. (See Monthly Volume Ranges)
     ec_average_ticket_range String Expected monthly volume range through eCheck. (See Average Volume Ranges)
     ec_high_ticket Int Expected maximum ticket through eCheck.
     swiped_percent Byte Percentage of commerce made through a swiped card.
     keyed_percent Byte Percentage of commerce made through entering card or bank information.
     ecommerce_percent Byte Percentage of commerce made through online transactions.
     app_complete_endpoint String Endpoint where the boarding webhook will be sent.
     dba_name String DBA name of the merchant. Matches the legal name if not provided.
     email String Primary email associated with the merchant.
     client_app_id String Optional client-issued unique identifier for an application. Enforcement of uniqueness must be performed on the client. (Returned unmodified).
     epic_app_id String EpicPay internal ID. Can be used to uniquely reference an application if a client_app_id is not supplied.
     epic_id String Unique identifier for the merchant.
status Object Status of the API Request.
   response_code String Processing status of the application. (See Appendix 13 for a complete list of Response Codes)
   reason_code String Currently unused.
   reason_text String A message that accompanies the reason_code.

 

Merchant Declined/Closed Webhook Object


Variable Description
result Object Result Object. (Not available when the response code is 'error'.)
   merchant_info Object Contains the merchant's application information.
     epic_id String Unique identifier for the merchant.
     dba_name String DBA name of the merchant. Matches the legal name if not provided.
     email String Primary email associated with the merchant.
     client_app_id String Optional client-issued unique identifier for an application. Enforcement of uniqueness must be performed on the client. (Returned unmodified).
     epic_app_id String EpicPay internal ID. Can be used to uniquely reference an application if a client_app_id is not supplied.
     location Object The Location Object.
status Object Status of the API Request.
   response_code String Processing status of the application. (See Appendix 13 for a complete list of Response Codes)
   reason_code String Currently unused.
   reason_text String A message that accompanies the reason_code.

 

Example Merchant Approval Webhook Object

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

{
    "result": {
        "gateway_credential": {
            "epic_id": "43123",
            "gateway_id": "00000000000000000000000000000000",
            "client_app_id": "12345",
            "epic_app_id": "7271bd8180684862928555caf201f156",
            "api_key_id": "API_Key",
            "api_key_password": "API_Pass"
        }
    },
    "status": {
        "response_code": "approved",
        "reason_code": "",
        "reason_text": "Application Approved"
    }
}

 

Example Pended Merchant Webhook Object

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

{
    "result": {
        "merchant_info": {
            "dba_name": "Discount Home Goods",
            "email": "totalhome@example.com",
            "client_app_id": "12345",
            "epic_app_id": "7271bd8180684862928555caf201f156",
            "epic_id": "43123"
        }
    },
    "status": {
        "response_code": "pended",
        "reason_code": "",
        "reason_text": "Application Pended"
    }
}

 

Example Extended Merchant Approval Webhook Object

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

{
    "result": {
        "gateway_credential": {
            "epic_id": "12345",
            "gateway_id": "00000000000000000000000000000000",
            "client_app_id": "12345",
            "epic_app_id": "7271bd8180684862928555caf201f156",
            "api_key_id": "API_Key",
            "api_key_password": "API_Pass"
        },
        "merchant_info": {
            "legal_name": "Total Home Goods, LLP.",
            "website": "http://www.example.com",
            "business_type": "school",
            "business_category": "education",
            "business_description": "School",
            "ownership_type": "llp",
            "fed_tax_id": "****0000",
            "is_test": "true",
            "location": {
                "address_line_1": "1200 West Hartford Pkwy.",
                "address_line_2": "Suite 2000",
                "city": "Dover",
                "state_province": "DE",
                "postal_code": "55022",
                "phone_number": "555-555-1212"
            },
            "primary_principal": {
                "first_name": "Bob",
                "last_name": "Fairview",
                "middle_name": "Nathaniel",
                "title": "Dr.",
                "date_of_birth": "2017-06-05",
                "ssn": "****1234",
                "ownership_percent": 100,
                "address_line_1": "1354 Oak St.",
                "address_line_2": "Unit 203",
                "city": "Dover",
                "state_province": "DE",
                "postal_code": "55022",
                "phone_number": "555-555-1234"
            },
            "bank_account": {
                "routing_number": "011103093",
                "account_number": "01234567890123",
                "account_holder_name": "Bob Fairview"
            },
            "cc_monthly_volume_range": "1",
            "cc_average_ticket_range": "5",
            "cc_high_ticket": 1500,
            "ec_monthly_volume_range": "2",
            "ec_average_ticket_range": "5",
            "ec_high_ticket": 1500,
            "swiped_percent": 0,
            "keyed_percent": 0,
            "ecommerce_percent": 100,
            "app_complete_endpoint": "http://www.example.com",
            "dba_name": "Total Home Goods, LLP.",
            "email": "totalhome@example.com",
            "client_app_id": "12345",
            "epic_app_id": "7271bd8180684862928555caf201f156",
            "epic_id": "12345"
        }
    },
    "status": {
        "response_code": "approved",
        "reason_code": "",
        "reason_text": "Application Approved"
    }
}

 

Example Merchant Declined/Closed Webhook Object

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 456
{
    "result": {
        "merchant_info": {
            "epic_id": "43123",
            "dba_name": "Total Home Goods, LLP.",
            "email": "totalhome@example.com",
            "client_app_id": "clientID",
            "epic_app_id": "7271bd8180684862928555caf201f156",
            "location": {
                "address_line_1": "1200 West Hartford Pkwy.",
                "address_line_2": "Suite 2000",
                "city": "Dover",
                "state_province": "DE",
                "postal_code": "55022",
                "phone_number": "555-555-1212"
            }
        }
    },
    "status": {
        "response_code": "closed",
        "reason_code": "",
        "reason_text": "Closed By Merchant"
    }
}

Merchant Boarding Webhook Tester


Appendix 1 - Contact Info Objects

 

Location Object


Property Description
address_line_1 String[100] Merchant's business address line 1.
address_line_2 String[20] Merchant's business address line 2.
city String[50] Merchant's business city.
state_province String[2] Merchant's business two-digit state or province code.
postal_code String[10] Merchant's business postal code.
phone_number String[20] Merchant's business phone number.

 

Primary Principal Object


Property Description
first_name String[20] Primary principal or signer's first name.
last_name String[20] Primary principal or signer's last name.
middle_name String[20] Primary principal or signer's middle name.
title String[20] Primary principal or signer's title.
date_of_birth Date[YYYY-MM-DD] Primary principal or signer's date of birth.
address_line_1 String[100] Primary principal or signer's residential address line 1.
address_line_2 String[20] Primary principal or signer's residential address line 2.
city String[50] Primary principal or signer's city.
state_province String[2] Primary principal or signer's two-digit state code.
postal_code String[10] Primary principal or signer's postal code.
ssn String[4] Last four digits of the primary principal or signer's social security number.
ownership_percent Integer[3] Percentage of business owned by primary principal or signer (must be between 0 and 100).
phone_number String[20] Primary principal or signer's phone number.

 

Contact Object


Additional contact or technical contact's information.

Property Description
first_name String[20] Contact's first name.
last_name String[20] Contact's last name.
email String[20] Contact's email address.
phone_number String[20] Contact's phone.

Appendix 2 - Bank Account Object


Property Description
routing_number String[9] Nine-digit Bank routing number.
account_number String[17] Bank account number.
account_holder_name String[40] Name on bank account.

 

Appendix 3 - Ownership Types


 

The type of ownership in which the business is registered.

Ownership Type Description
c Public Corporation
gov Government
llc Limited Liability Company
llp Limited Liability Partnership
np Non-Profit Charitable Organization
p Partnership
po Political Organization
s Private Corporation
sp Sole Proprietor
te Other Tax Exempt

Appendix 4 - Reason 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 "e01" and "E01" as identical values).

Code Description
E01 Unauthorized.
E02 Invalid Request.
E03 Invalid Request Header.
E04 Invalid Request Data.
E99 Error.

 

Appendix 5 - Average Ticket Ranges


Value Description
1 Under $16
2 $16-$25
3 $26-$50
4 $51-$250
5 $251-$500
6 $501-$1,000
7 More than $1,000

 

Appendix 6 - Monthly Volume Ranges


Value Description
1 Under $5,000
2 $5,000-$10,000
3 $10,001-$25,000
4 $25,001-$50,000
5 $50,001-$100,000
6 $100,001-$165,000
7 More than $165,000

 

Appendix 7 - Business Categories and Business Types


Business Category Business Type Description
beauty_and_personal_care beauty_salon Beauty Salon
beauty_and_personal_care hair_salon_barbershop Hair Salon/Barbershop
beauty_and_personal_care independent_stylist_barber Independent Stylist/Barber
beauty_and_personal_care massage_therapist Massage Therapist
beauty_and_personal_care nail_salon Nail Salon
beauty_and_personal_care other Other
beauty_and_personal_care spa Spa
beauty_and_personal_care tanning_salon Tanning Salon
beauty_and_personal_care tattoo_piercing Tattoo/Piercing
casual_use events_festivals Events/Festivals
casual_use miscellaneous_goods Miscellaneous Goods
casual_use miscellaneous_services Miscellaneous Services
casual_use other Other
casual_use outdoor_markets Outdoor Markets
education child_care Child Care
education instructor_teacher Instructor/Teacher
education other Other
education school School
education tutor Tutor
food_and_drink bakery Bakery
food_and_drink bar_club_lounge Bar/Club/Lounge
food_and_drink caterer Caterer
food_and_drink coffee_tea_shop Coffee/Tea Shop
food_and_drink convenience_store Convenience Store
food_and_drink food_truck_cart Food Truck/Cart
food_and_drink grocery_market Grocery/Market
food_and_drink other Other
food_and_drink outdoor_markets Outdoor Markets
food_and_drink private_chef Private Chef
food_and_drink quick_service_restaurant Quick Service Restaurant
food_and_drink sit_down_restaurant Sit-Down Restaurant
food_and_drink specialty_shop Specialty Shop
health_care_and_fitness acupuncture Acupuncture
health_care_and_fitness alternative_medicine Alternative Medicine
health_care_and_fitness care_giver Care Giver
health_care_and_fitness chiropractor Chiropractor
health_care_and_fitness dentist_orthodontist Dentist/Orthodontist
health_care_and_fitness gym_health_club Gym/Health Club
health_care_and_fitness massage_therapist Massage Therapist
health_care_and_fitness medical_practitioner Medical Practitioner
health_care_and_fitness optometrist_laser_eye_surgery Optometrist/Eye Care
health_care_and_fitness other Other
health_care_and_fitness personal_trainer Personal Trainer
health_care_and_fitness psychiatrist Psychiatrist
health_care_and_fitness therapist Therapist
health_care_and_fitness veterinary_services Veterinary Services
home_and_repair automotive_services Automotive Services
home_and_repair carpet_cleaning Carpet Cleaning
home_and_repair cleaning Cleaning
home_and_repair clothing_alterations Clothing Alteration
home_and_repair computer_electronics_and_appliance_repair Computer/Electronics/Appliances
home_and_repair dry_cleaning_and_laundry Dry Cleaning and Laundry
home_and_repair electrical_services Electrical Services
home_and_repair flooring Flooring
home_and_repair general_contracting General Contracting
home_and_repair heating_and_air_conditioning Heating and Air Conditioning
home_and_repair installation_services Installation Services
home_and_repair junk_removal Junk Removal
home_and_repair landscaping Landscaping
home_and_repair locksmith_services Locksmith Services
home_and_repair moving Moving
home_and_repair other Other
home_and_repair painting Painting
home_and_repair pest_control Pest Control
home_and_repair plumbing Plumbing
home_and_repair roofing Roofing
home_and_repair shoe_repair Shoe Repair
home_and_repair watch_jewelry_repair Watch/Jewelry Repair
leisure_and_entertainment airlines Airlines and Airline Carriers
leisure_and_entertainment car_rental Car Rental
leisure_and_entertainment events_festivals Events/Festivals
leisure_and_entertainment lodging Hotels, Motels, Resorts, Central Reservation Services
leisure_and_entertainment movies_film Movies/Film
leisure_and_entertainment museum_cultural Museum/Cultural
leisure_and_entertainment music Music
leisure_and_entertainment other Other
leisure_and_entertainment performing_arts Performing Arts
leisure_and_entertainment sporting_events Sporting Events
leisure_and_entertainment sports_recreation Sports Recreation
leisure_and_entertainment tourism Tourism
non_profit automobile_association Automobile Association
non_profit charitable_organization Charitable and Social Service Organization
non_profit civic_social_and_fraternal_association Civic, Social, and Fraternal Association
non_profit membership_organization Membership Organizations (Not Elsewhere Classified)
non_profit political_organization Political Organization
non_profit religious_organization Religious Organization
professional_services accounting Accounting
professional_services child_care Child Care
professional_services consulting Consulting
professional_services delivery Delivery
professional_services design Design
professional_services interior_design Interior Design
professional_services legal_services Legal Services
professional_services marketing_advertising Marketing/Advertising
professional_services nanny_services Nanny Services
professional_services notary_services Notary Services
professional_services other Other
professional_services photography Photography
professional_services printing_services Printing Services
professional_services real_estate Real Estate
professional_services software_development Software Development
retail art_photo_and_film Art, Photo and Film
retail books_mags_music_and_video Books, Mags, Music and Video
retail clothing_and_accessories Clothing and Accessories
retail convenience_store Convenience Store
retail electronics Electronics
retail eyewear Eyewear
retail flowers_and_gifts Flowers and Gifts
retail furniture_home_goods Furniture/Home Goods
retail grocery_market Grocery/Market
retail hardware_store Hardware Store
retail hobby_shop Hobby Shop
retail jewelry_and_watches Jewelry and Watches
retail office_supply Office Supply
retail other Other
retail outdoor_markets Outdoor Markets
retail pet_store Pet Store
retail specialty_shop Specialty Shop
retail sporting_goods Sporting Goods
transportation bus Bus
transportation delivery Delivery
transportation limousine Limousine
transportation moving Moving
transportation other Other
transportation private_shuttle Private Shuttle
transportation taxi Taxi
transportation town_car Town Car

 

Appendix 8 - Payment Types


Value Description
eCom Payfac Credit Card.
ACH Epic ACH.

 

Appendix 9 - Transaction Types


Value Description
Sale Credit Card Sale.
Debit ACH Sale.
Credit ACH Refund.
Return Credit Card Return.

 

Appendix 10 - App Delivery Types


Value Description
direct EpicPay emails the app link directly to the merchant. Merchant will not be required to enter PIN.
link_full_page Full page link returned in the response. PIN will be required (sent to Merchant's email as entered).
link_iframe iFrame link returned in the response. PIN will be required (sent to Merchant's email as entered).

 

Appendix 11 - Alternate Bank Deposit Types


Value Description
fees_only Processing Fees are deducted from Alternate bank account.
fees_adjustments Fees and Adjustments, including Chargebacks or ACH Rejects, are deducted from Alternate bank account.
fees_adjustments_refunds Fees, Adjustments, and Refunds are deducted from Alternate bank account.

 

Appendix 12 - Alternate Bank Account Object


Property Description
routing_number String[9] Nine-digit Bank routing number.
account_number String[17] Bank account number.
account_holder_name String[40] Name on bank account.
deposit_type String[30] Type of Deposit. See Alternate Bank Account Deposit Type

 

Appendix 13 - Response 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 "Received" and "received" as identical values).

Code Reason Text Description
Received "" Indicates a successful application submission/request.
Error See Reason Codes Indicates an unsuccessful application submission/request.
Pended "Application Pended" Indicates the application is under review for approval.
Approved "Application Approved" Indicates a successful application and a successfully boarded merchant.
Declined "Merchant is declined" Indicates the application was rejected upon review, or was withdrawn by the merchant.
Closed "Closed By Merchant" Indicates that the merchant account has been closed by the merchant.
Closed "Closed By EpicPay" Indicates that the merchant account has been closed by EpicPay.
Closed "Closed By Risk" Indicates that the merchant account has been closed by the EpicPay Risk department.

Boarding API Version History


Version Revision Date Description
2.0.1 1/17/2020 Added the Merchant Closed Webhook Object under the Webhooks section and to the webhook tester. This is the same as Declined, but returns a different "response_code" if the merchant account is closed.
1.6.1 11/27/2019 Added the Merchant Declined Webhook Object under the Webhooks section.
1.5.2 11/13/2019 Added the Using the MPA iframe section. Added new webhook payloads for the merchant application status under Webhooks. Updated the webhook tester to use the new payloads.
1.4.1 10/30/2019 Updated "response_code" and "reason_code" for boarding and webhook responses.
1.3.4 9/05/2019 Added custom field values to the Boarding Webhook Tester.
1.3.3 8/28/2019 Clarified requirements for "business_type" and "business_category" on the boarding request.
1.3.2 6/28/2019 Clarified requirements in Board a Merchant regarding "business_category" and "business_type". Added a Webhooks section to Merchant Boarding.
1.3.0 12/26/2018 Upgrade to the Authentication Process (Api Key ID / Password)