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.

 

SSL Certification

  • All requests must be made over 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, 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 a Merchant Processing Application. 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.

     

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

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 Processing status of the transaction.
   reason_code String Three-digit code indicates the approval status of a transaction. (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": ""
  }
}

Webhooks

 

Introduction


EpicPay partners can opt to receive a webhook whenever one of their pending merchant applications is approved by EpicPay. 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 Boarding Webhook Object


Variable Description
status Object Status of the API Request.
   response_code String Processing status of the transaction.
   reason_code String Three-digit code indicates the approval status of a transaction. (See Appendix 4 for a complete list of Reason Codes)
   reason_text String A message that accompanies the reason_code.
result Object Result Object. (Not available when the response code is 'error'.)
   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 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.
   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.

 

Example Merchant Boarding Webhook Object

{
  "result": {
    "gateway_credential": {
      "epic_id": "43123",
      "gateway_id": "00000000000000000000000000000000",
      "client_app_id": "12345",
      "epic_app_id": "1213",
      "api_key_id": "test_api_key",
      "api_key_password": "test_api_pass"
    }
  },
  "status": {
    "response_code": "Approved",
    "reason_code": "000",
    "reason_text": "Approved"
  }
}

 

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


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

 

Revision History


Version Revision Date Description
1 9/05/2019 Added custom field values to the Boarding Webhook Tester.
1 8/28/2019 Clarified requirements for "business_type" and "business_category" on the boarding request.
1 6/28/2019 Clarified requirements in Board a Merchant regarding business_category and business_type. Added a Webhooks section to Merchant Boarding.
1 12/26/2018 Upgrade to the Authentication Process (Api Key ID / Password)