Boarding API

Introduction

The EpicPay Gateway Agent API is a web service that allows Fortis 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 Fortis, 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://board-api.epicpay.com/v1/

API Keys

These credentials will be different from the Payment API credentials. Please contact Fortis to get your EpicPay Gateway 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 Gateway 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. For security reasons, all API requests that use Basic Authentication must be made from the server-side.

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

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

• Method:

  POST

• Authorization:

  Basic:

API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

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

  • 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: Integer Average credit card transaction amount in dollars (Applicable when Template Application Type is 'credit_card' or 'both').

  • cc_monthly_volume: Integer Average monthly credit card volume in dollars (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: Integer Average eCheck transaction amount in dollars (Applicable when Template Application Type is 'echeck' or 'both').

  • ec_monthly_volume: Integer Average monthly echeck volume in dollars (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.

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

  • preferred_language String Merchant’s preferred language. English(“en-US”) will be used if no value is supplied. See Preferred Language for supported values.

   

Boarding Request Variables

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

{
    "template_id": "7564",
    "client_app_id": "12345",
    "email": "totalhome@example.com",
    "dba_name": "Discount Home Goods",
    "app_delivery": "direct",
    "website": "http://www.example.com",
    "ownership_type": "llp",
    "fed_tax_id": "00-0000000",
    "cc_average_ticket": 15,
    "cc_monthly_volume": 10000,
    "cc_high_ticket": 1500,
    "ec_average_ticket": 25,
    "ec_monthly_volume": 2000,
    "ec_high_ticket": 1500,
    "business_type": "school",
    "business_category": "education",
    "business_description": "School",
    "preferred_language": "en-US"
    "swiped_percent": 0,
    "keyed_percent": 0,
    "ecommerce_percent": 100,
    "legal_name": "Total Home Goods, LLP.",
    "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",
        "address_line_1": "1354 Oak St.",
        "address_line_2": "Unit 203",
        "city": "Dover",
        "state_province": "DE",
        "postal_code": "55022",
        "ssn": "1234",
        "ownership_percent": 100,
        "phone_number": "555-555-1234"
    },
    "contact": {
        "first_name": "Jeffery",
        "last_name": "Todd",
        "email": "jtodd@example.com",
        "phone_number": "555-555-3456"
    },
    "bank_account": {
        "account_holder_name": "Bob Fairview",
        "routing_number": "011103093",
        "account_number": "01234567890123"
    },
    "app_complete_endpoint": "http://www.example.com"
}

Boarding Response

Boarding Response Variables

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

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

Example iframe Message

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

Webhooks

Introduction

Fortis partners can opt to receive a webhook whenever one of their merchant applications is pended, approved, or declined by Fortis. 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

Extended Merchant Approval Webhook Object

Merchant Pended Webhook Object

Merchant Declined/Closed Webhook Object

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 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": 10000,
            "cc_average_ticket": 15,
            "cc_high_ticket": 1500,
            "ec_monthly_volume": 2000,
            "ec_average_ticket": 25,
            "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 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 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

Primary Principal Object

Contact Object

Additional contact or technical contact's information.

Appendix 2 - Bank Account Object

Appendix 3 - Ownership Types

The type of ownership in which the business is registered.

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

Appendix 5 - Average Ticket Ranges

Appendix 6 - Monthly Volume Ranges

Appendix 7 - Business Categories and Business Types

Appendix 8 - Payment Types

Appendix 9 - Transaction Types

Appendix 10 - App Delivery Types

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

Appendix 12 - Preferred Language

Boarding API Version History