Reporting API

Introduction

The EpicPay Gateway Reporting API is a web service that allows EpicPay Gateway merchants to generate reports. The EpicPay Gateway Reporting API implements REST architecture style. Request and response messages, including errors, are in JSON format.

Intended Audience

This document is intended for developers who want to understand and implement the EpicPay Gateway Reporting API.

BaseURL

https://rpt-api.epicpay.com/reporting/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 Reporting API, you will need to provide your terminal credentials. They are:

• API Key ID: This value identifies a terminal, which is unique to a merchant.
• Password: Authenticates the EpicPay Gateway Reporting 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.

• Please Note: For merchants with multiple terminals: All reports return data for all terminals. Changing the terminal used for authentication will not change the data returned by these reports.

Sandbox

The EpicPay Gateway Reporting API Sandbox was designed for developers to test the EpicPay Gateway Reporting API. While testing the API, use the BaseURL in the "Sandbox API" section below. After you have confirmed that your test requests work properly on the sandbox, simply update your API Key ID and Password to use an API Key for a Production Terminal, and change the URL of your requests to the Production BaseURL (See the "Introduction" section above).

Sandbox Registration

To use the Sandbox, you will need to Register a new Sandbox Account.

Once you have received your Sandbox User Account credentials, you will need to configure your Sandbox Terminal before you can use the Sandbox API. If you already have Sandbox credentials from the EpicPay Gateway Payment API, you can use them for the Reporting API as well.

Sandbox API Keys

Before you can use the Sandbox API, you must first generate an API Key for one your Sandbox Terminals.

To generate an API Key for a Sandbox Terminal, go to the EpicPay Gateway Sandbox Virtual Terminal and log in using your Sandbox User Account credentials (which you should have set up in the previous step: "Sandbox Registration". 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.

Sandbox API Version and BaseURL

The current Sandbox version is Version 1.0

BaseURL (Sandbox)

https://sandbox-api.epicpay.com/reporting/v1/

Sandbox Virtual Terminal (Web Application)

Note: This is NOT the Sandbox API BaseURL. See "Sandbox API Version and BaseURL" above.

Sandbox Virtual Terminal: https://sandbox-vt.epicpay.com/

Reports

EpicPay Gateway merchants can generate reports using the "GetReport" method. To use this method, you must include the report_type as part of the URL. See the Report Types section for more information about the reports that can be generated. Report data will be returned in JSON format.

Generate a Report:

Use this method to generate one of the reports.

• URL

  BaseURL/getreport/report_type

• Method:

  POST

• Authorization:

  Basic: API Key ID : Password

• Headers:

  • Content-Type: application/json

• Data:

  Required:

  • start_date: [Date (YYYY-MM-DD)] The beginning date for the report.
  • end_date: [Date (YYYY-MM-DD)] The ending date for the report.

   

Report Request Variables

Report Response

Report Response Variables

Report Types

These are the types of reports that can be generated. To request a report, use the GetReport method, passing in the 'report_type' part of the URL. The Data object returned will be unique to the report type.

Batches Report

Data Object - Batches Report

Example Request - Batches Report

POST {BaseURL}/getreport/batches HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2017-08-05",
  "end_date": "2017-08-15"
}

Example Response - Batches Report

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

{
  "result": {
    "filters": {
      "start_date": "2017-08-09",
      "end_date": "2017-08-10"
    },
    "record_count": 24,
    "data": [
      {
        "batch_id": "9324",
        "reported_date": "2017-08-05",
        "settled_date": "2017-08-08",
        "epic_id": "30",
        "merchant_name": "Test DBA",
        "payment_type": "eCom",
        "sales_count": 1,
        "sales_amount": 3000.56,
        "sales_amount2": 7.21,
        "credits_count": 1,
        "credits_amount": 2.26,
        "credits_amount2": 1.12,
        "agent_id": "0012",
        "agent_name": "Jane Doe"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

ACH Reject Report

Data Objects

Example Request - ACH Rejects Report

POST {BaseURL}/getreport/achrejects HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZC
Content-Type: application/json

{
  "start_date": "2017-08-12",
  "end_date": "2017-08-22"
}

Example Response (ACH Rejects)

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

{
  "result": {
    "filters": {
      "start_date": "2017-08-12",
      "end_date": "2017-08-22"
    },
    "record_count": 24,
    "data": [
      {
        "reported_date": "2017-08-11",
        "settled_date": "",
        "effective_date": "2017-08-10",
        "trxn_id": "01231",
        "account_number": "0123456****123",
        "amount": 123.12,
        "reason_code": R03",
        "account_holder": "Frodo Baggins",
        "addenda": "",
        "entry_class":"WEB",
        "entry_desc":"PAYMENT",
        "routing_number":"021000021",
        "reason_text":"No Account/Unable to Locate Account"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Deposits Report

Data Objects

Example Request - Deposits Report

POST {BaseURL}/getreport/deposits HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2017-08-12",
  "end_date": "2017-08-22"
}

Example Response (Deposits)

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

{
  "result": {
    "filters": {
      "start_date": "2017-08-12",
      "end_date": "2017-08-22"
    },
    "record_count": 24,
    "data": [
      {
        "reported_date": "2017-08-07",
        "effective_date": "2017-08-08",
        "epic_id": "123478",
        "merchant_name": "Test DBA account",
        "payment_type": "eCom",
        "account_number": "123456****0123",
        "amount": 5500.34,
        "agent_id": "0012",
        "agent_name": "Jane Doe",
        "unique_id": "1234567"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Deposits Detail Report

Data Objects

Detail Transaction Objects

Example Request - Deposits Detail Report

POST {BaseURL}/getreport/deposits-detail HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2017-08-12",
  "end_date": "2017-08-22"
}

Example Response (Deposits Detail)

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

{
  "result": {
    "filters": {
      "start_date": "2017-08-12",
      "end_date": "2017-08-22"
    },
    "record_count": 24,
    "data": [
      {
        "reported_date": "2017-08-07",
        "effective_date": "2017-08-08",
        "epic_id": "123478",
        "merchant_name": "Test DBA account",
        "payment_type": "eCom",
        "account_number": "123456****0123",
        "amount": 5500.34,
        "agent_id": "0012",
        "agent_name": "Jane Doe",
        "unique_id": "1234567",
        "detail_count": 4,
        "detail_data": [
          {
            "trxn_type": "SALE",
            "reported_date": "2017-08-07",
            "amount": 125.25,
            "secondary_amount": 0,
            "account_no": "0123456****1234",
            "accountholder": "John Johnson",
            "transaction_date": "2017-08-07",
            "client_trxn_id": "Test123",
            "client_order_id": "TestOrder1",
            "client_customer_id": "TestTrxn1",
            "reference_id": "trxn_000009",
            "memo": "bat_594044"
          },
          ...
        ]
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Transaction Activity Report

Data Objects

Example Request - Transaction Activity Report

POST {BaseURL}/getreport/trxnactivity HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Transaction Activity)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "bin": "123456",
        "account_suffix": "1234",
        "client_trxn_id": "Test123",
        "client_order_id": "TestOrder1",
        "client_customer_id": "TestTrxn1",
        "mid": "88888888",
        "deposited_date": "2018-04-25",
        "batch_id": "123779",
        "accountholder": "John Johnson",
        "amount": 123.45,
        "secondary_amount": 0.01,
        "account_number": "0123456****1234",
        "settled_date": "2018-04-25",
        "trxn_type": "SALE",
        "payment_type": "CARD",
        "reported_date": "2018-04-25",
        "transaction_id": "000009",
        "trxn_utc_date": "2018-04-25",
        "reason_code": "000",
        "reason_text": "Test Only"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Chargebacks Report

Data Objects

Example Request - Chargebacks Report

POST {BaseURL}/getreport/chargebacks HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Chargebacks)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "reason_code": "TST",
        "deposited_date": "2018-04-26",
        "cycle": "FIRST_CHARGEBACK",
        "activity": "Assign To Merchant",
        "activity_date": "2018-04-26",
        "transaction_currency": 1,
        "transaction_amount": 100,
        "trxn_utc_date": "2018-04-26",
        "authorization_currency": 1,
        "authorization_amount": 100,
        "authorization_date": "2018-04-26",
        "chargeback_amount": 50,
        "reason_text": "Sandbox TEST Data - Chargeback",
        "account_suffix": "6378",
        "bin": "123456",
        "mid": "88888888",
        "epic_id": "00001",
        "date_reply_by": "2018-04-26",
        "chargeback_type": 1,
        "case_id": "99999999999999",
        "date_reported": "2018-04-26",
        "chargeback_currency": 1,
        "card_number": "0123456****1234"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Active Subscriptions Report

Data Objects

Example Request - Active Subscriptions Report

POST {BaseURL}/getreport/activesubscriptions HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Active Subscriptions)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "subscription_id": "f7991178-0e6e-481f-b89d-c34d0e9123a9",
        "customer_id": "0d541381-bcfd-47a1-b9e4-f9be74f11111",
        "wallet_id": "b64b3a3f-eb3b-40b2-a2c8-f005df94d26d",
        "terminal_id": 0,
        "status": "Active",
        "amount": 12.34,
        "secondary_amount": 0.42,
        "last_amount": 18.21,
        "last_secondary_amount": 0.21,
        "currency": "USD",
        "frequency": "Twice_Every_Month",
        "period": 0,
        "date_of_month_1": 5,
        "date_of_month_2": 15,
        "total_payments": 12,
        "alert_after": true,
        "next_payment_date": "2018-04-25",
        "last_payment_date": "2018-04-25",
        "merchant_id": "2123123",
        "terminal_name": "Default Terminal",
        "accountholder": "John Johnson",
        "account_type": "Visa",
        "account_suffix": "1234",
        "account_expiration_date": "0224",
        "customer_first_name": "Mary",
        "customer_last_name": "Johnson"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Suspended Subscriptions Report

Data Objects

Example Request - Suspended Subscriptions Report

POST {BaseURL}/getreport/suspendedsubscriptions HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Suspended Subscriptions)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "subscription_id": "5307b89c-21ca-4fd2-b409-7be1f78b054d",
        "client_order_id": "12344567",
        "amount": 12.34,
        "secondary_amount": 0.42,
        "last_amount": 18.21,
        "last_secondary_amount": 0.21,
        "frequency": "Every_n_Days",
        "period": 5,
        "next_payment_date": "2018-04-25",
        "last_payment_date": "2018-04-25",
        "total_payments": 12,
        "wallet_id": "19f3812a-816f-41fc-b6bc-ebe9d6e57b61",
        "customer_first_name": "Mary",
        "customer_last_name": "Johnson",
        "accountholder": "John Johnson",
        "account_type": "Visa",
        "account_suffix": "1234",
        "account_expiration_date": "0224",
        "terminal_id": 560,
        "terminal_name": "Default Terminal",
        "subscription_suspend_reason": "Maximum number of retries exceeded",
        "subscription_suspend_date": "2018-04-25"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Subscriptions with Wallet Trouble Report

Data Objects

Example Request - Subscriptions with Wallet Trouble Report

POST {BaseURL}/getreport/wallettrouble HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Subscriptions with Wallet Trouble)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "subscription_id": "529c2052-2ad3-46f8-8009-bf957f67519b",
        "client_order_id": "12344567",
        "amount": 12.34,
        "secondary_amount": 0.42,
        "last_amount": 18.21,
        "last_secondary_amount": 0.21,
        "frequency": "Every_n_Days",
        "period": 5,
        "next_payment_date": "2018-04-25",
        "last_payment_date": "2018-04-25",
        "total_payments": 12,
        "wallet_id": "d729d5af-eb66-44c8-9177-7e0e422fcc3c",
        "customer_first_name": "Mary",
        "customer_last_name": "Johnson",
        "accountholder": "John Johnson",
        "account_type": "Visa",
        "account_suffix": "1234",
        "account_expiration_date": "0224",
        "terminal_id": 0,
        "terminal_name": "Default Terminal",
        "wallet_suspend_reason": "Expired card",
        "wallet_suspend_date": "2018-04-25"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

New Scheduled Payments Report

Data Objects

Example Request - New Scheduled Payments Report

POST {BaseURL}/getreport/newpayments HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (New Scheduled Payments)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "schedule_id": 123354322,
        "scheduled_date": "2018-04-25",
        "amount": 12.34,
        "secondary_amount": 0.42,
        "alert_after_sent": true,
        "alert_before_sent": true,
        "wallet_id": "bcd1d721-ce18-4ffe-b229-585bef7c9e31",
        "customer_first_name": "Mary",
        "customer_last_name": "Johnson",
        "accountholder": "John Johnson",
        "account_type": "Visa",
        "account_suffix": "1234",
        "account_expiration_date": "0224",
        "terminal_id": 15,
        "terminal_name": "Default Terminal",
        "subscription_id": "98672de5-f7e3-42d7-bcb9-db486f0529e0",
        "client_order_id": "12344567",
        "status": "Scheduled",
        "transaction_id": "6220223",
        "transaction_date": "2018-04-25",
        "transaction_status": "Approved",
        "reason_code": "000",
        "response_message": "Approved"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Failed Scheduled Payments Report

Data Objects

Example Request - Failed Scheduled Payments Report

POST {BaseURL}/getreport/failedpayments HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Failed Scheduled Payments)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "schedule_id": 123354322,
        "scheduled_date": "2018-04-25",
        "amount": 12.34,
        "secondary_amount": 0.42,
        "alert_after_sent": true,
        "alert_before_sent": true,
        "wallet_id": "bcd1d721-ce18-4ffe-b229-585bef7c9e31",
        "customer_first_name": "Mary",
        "customer_last_name": "Johnson",
        "accountholder": "John Johnson",
        "account_type": "Visa",
        "account_suffix": "1234",
        "account_expiration_date": "0224",
        "terminal_id": 15,
        "terminal_name": "Default Terminal",
        "subscription_id": "98672de5-f7e3-42d7-bcb9-db486f0529e0",
        "client_order_id": "12344567",
        "status": "Failed",
        "transaction_id": "885323",
        "transaction_date": "2018-04-25",
        "transaction_status": "Approved",
        "reason_code": "000",
        "response_message": "Approved"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Successful Scheduled Payments Report

Data Objects

Example Request - Successful Scheduled Payments Report

POST {BaseURL}/getreport/successfulpayments HTTP/1.1
Authorization: Basic czZCaGfSafSa3F0ZCaGfMzpn3Mfpn3DFSa3FZCaGf0M
Content-Type: application/json

{
  "start_date": "2018-04-01",
  "end_date": "2018-04-30"
}

Example Response (Successful Scheduled Payments)

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

{
  "result": {
    "filters": {
      "start_date": "2018-04-01",
      "end_date": "2018-04-30"
    },
    "record_count": 10,
    "data": [
      {
        "schedule_id": 123354322,
        "scheduled_date": "2018-04-25",
        "amount": 12.34,
        "secondary_amount": 0.42,
        "alert_after_sent": true,
        "alert_before_sent": true,
        "wallet_id": "6b9b08eb-d828-4cbb-9b94-478094e46b7b",
        "customer_first_name": "Mary",
        "customer_last_name": "Johnson",
        "accountholder": "John Johnson",
        "account_type": "Visa",
        "account_suffix": "1234",
        "account_expiration_date": "0224",
        "terminal_id": 0,
        "terminal_name": "Default Terminal",
        "subscription_id": "6202a6fb-a129-40a5-a3ac-6b9cae5a8647",
        "client_order_id": "12344567",
        "status": "Processed",
        "transaction_id": "0220223",
        "transaction_date": "2018-04-25",
        "transaction_status": "Approved",
        "reason_code": "000",
        "response_message": "Approved"
      },
      ...
    ]
  },
  "status": {
    "response_code": "Received",
    "reason_code": "",
    "reason_text": ""
  }
}

Appendix 1 - Reason Codes

Appendix 2 - Payment Types

Appendix 3 - Transaction Types

Reporting API Version History