Introduction


The EpicPay Gateway Reporting API is a web service that allows EpicPay 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.

 

SSL Certification

  • All requests must be made over 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 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.

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


Variable Description
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_type String The unique identifier for the Report Type to be generated. (This identifier is required in order to return a valid report).

 

Report Response

 

Report Response Variables


Variable Description
status Object The status of the API Request.
   response_code String The processing status of the report.
   reason_code String Three-digit code indicates the approval status of a report. (See Appendix 1 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'.
   record_count Integer The number of records returned.
   filters Object The filters used to generate this report.
     start_date Date[YYYY-MM-DD] The beginning date for the report. (Returned unmodified).
     end_date Date[YYYY-MM-DD] The end date for the report. (Returned unmodified).
   data Array A list of objects that contain the report data. The objects in this list will be specific to the type of report generated.

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.

 

Report Type Description
batches The summary of batches per merchant within a selected date range.
achrejects Returns all ACH rejects and Notices of Change within a selected date range.
deposits The summary of all deposits made by merchant within a selected date range.
deposits-detail The summary of all deposits made by merchant within a selected date range. Each item includes detailed transaction data.
trxnactivity Returns all settled transactions, chargebacks, and ACH rejects within a selected date range.
chargebacks Returns all chargebacks within a selected date range.
activesubscriptions Returns all active subscriptions. Date range filters are not applicable to this report.
suspendedsubscriptions Returns all suspended subscriptions created within a selected date range.
wallettrouble Returns all subscriptions with wallet trouble (wallet is suspended, expired, etc.). Date range filters are not applicable to this report.
newpayments Returns all new scheduled payments created within a selected date range. (Scheduled payments originate from subscriptions)
failedpayments Returns all failed scheduled payments created within a selected date range. (Scheduled payments originate from subscriptions)
successfulpayments Returns all successful scheduled payments created within a selected date range. (Scheduled payments originate from subscriptions)

 

Batches Report


Data Object - Batches Report

Property Description
batch_id String Unique identifier for the batch. This ID is the same as 'batch_id' on the 'Settled Transactions' report.
reported_date Date[YYYY-MM-DD] Report Date.
settled_date Date[YYYY-MM-DD] Date the funds will be available in the merchant's bank account.
epic_id String Unique identifier for the Merchant.
merchant_name String Merchant's "Doing Business As" name.
payment_type String Indication of the Type of Payments submitted.
sales_count Integer Number of credit card sales and ACH debits in the batch.
sales_amount Decimal Gross sale amount.
sales_amount2 Decimal Secondary amount collected if necessary. Split from sales amount and deposited into FBO2.
credits_count Integer The number of refund and credit transactions in the batch.
credits_amount Decimal Gross refund and credit amount.
credits_amount2 Decimal Secondary credit amount collected if necessary. Deducted from FBO2.
agent_id String Unique identifier for the Agent.
agent_name String Agent's name.

 

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

Property Description
reported_date Date[YYYY-MM-DD] The date that the processing bank reported the ACH Reject to EpicPay.
effective_date Date[YYYY-MM-DD] The date that the account holder's bank issued the ACH Reject to EpicPay.
settled_date Date[YYYY-MM-DD] The date that the ACH Reject was settled.
trxn_id Integer Unique identifier for the transaction that was rejected.
account_number Integer Checkwriter's bank account number provided in the gateway.
amount Decimal Amount that was rejected.
reason_code String Codes beginning with 'R' indicate the debit or credit that was rejected. Codes beginning with 'C' are correction notices for debits and credits that were not rejected.
accountholder String The name of the account holder as it appears on the account.
addenda String For ACH Rejects, this holds a description of the reject. For Notices of Change, this holds the new value of the changed data.
entry_class String The SEC Code that was used for the ACH Transaction.
entry_desc String An optional client-defined descriptor for the ACH Transaction.
routing_number String The 9-digit Bank Routing Number (ABA) used for the ACH Transaction.
reason_text String A message that accompanies the reason_code.

 

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

Property Description
reported_date Date[YYYY-MM-DD] The date that the deposit was initiated by EpicPay.
effective_date Date[YYYY-MM-DD] The expected date that this deposit will appear in the merchant's bank account.
epic_id String Unique identifier for the Merchant.
merchant_name String[100] Merchant "Doing Business As" name.
payment_type String Type of transactions to which this deposit applies (Values: 'eCom', 'ACH' ).
account_number Integer Bank Account Number (masked) that received this deposit.
amount Integer Amount credited or debited to merchant's bank account.
agent_id String Unique identifier for the Agent.
agent_name String Agent's name.
unique_id String Unique identifier for the deposit record.

 

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

Property Description
reported_date Date[YYYY-MM-DD] The date that the deposit was initiated by EpicPay.
effective_date Date[YYYY-MM-DD] The expected date that this deposit will appear in the merchant's bank account.
epic_id String Unique identifier for the Merchant.
merchant_name String[100] Merchant "Doing Business As" name.
payment_type String Type of transactions to which this deposit applies (Values: 'eCom', 'ACH' ).
account_number Integer Bank Account Number (masked) that received this deposit.
amount Integer Amount credited or debited to merchant's bank account.
agent_id String Unique identifier for the Agent.
agent_name String Agent's name.
unique_id String Unique identifier for the deposit record.
detail_count Integer Number of detail transaction records returned.
detail_data Array List of Detail Transaction objects.

 

Detail Transaction Objects

Property Description
trxn_type String The Transaction Type.
reported_date Date[YYYY-MM-DD] Report Date. Typically the date of the transaction.
amount Decimal Transaction amount.
secondary_amount Decimal Secondary transaction amount.
account_no String[4-17] Credit Card or Bank Account Number (masked).
accountholder String The name of the account holder as it appears on the account.
transaction_date Date[YYYY-MM-DD] The date of the transaction.
client_trxn_id String Client transaction id passed in by the client. EpicPay returns this id unchanged.
client_order_id String Client order id passed in by the client. EpicPay returns this id unchanged.
client_customer_id String Client customer id passed in by the client. EpicPay returns this id unchanged.
reference_id String Id of transaction referenced.
memo String Additional notes or description of the referenced item.

 

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

Property Description
bin String Bank Identification Number: first 6 digits of the credit card number used; or the 9 digits bank routing number of the bank account used.
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
client_trxn_id String Client transaction id passed in by the client. EpicPay returns this id unchanged.
client_order_id String Client order id passed in by the client. EpicPay returns this id unchanged.
client_customer_id String Client customer id passed in by the client. EpicPay returns this id unchanged.
mid String Merchant identifier for transaction processing.
deposited_date Date[YYYY-MM-DD] The date the transaction was settled to the merchant account.
batch_id String Unique identifier for the Batch in which this transaction was included. This ID is the same as 'batch_id' on the 'Batches' report.
accountholder String Account name as provided to the EpicPay Gateway by the consumer.
amount Decimal Gross transaction amount.
secondary_amount Decimal Secondary amount collected if necessary. Not deposited to merchant.
account_number String The account number associated with the transaction. (Returns with some digits obscurred)
settled_date Date[YYYY-MM-DD] The date the transaction was settled to the customer account.
trxn_type String The Transaction Type.
payment_type String The Type of Payment used for this transaction.
reported_date Date[YYYY-MM-DD] Report Date. Typically the date of the transaction.
transaction_id String The unique identifier for the transaction.
trxn_utc_date Date[YYYY-MM-DD] The date the transaction was placed (in UTC Time).
reason_code String Three-digit code indicates the approval status of a transaction.
reason_text String A message that accompanies the reason_code.

 

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

Property Description
deposited_date Date[YYYY-MM-DD] The date the funds for the transaction were deposited in the merchant's bank account.
cycle String The stage in the chargeback lifecycle.
activity String The activity associated with this chargeback record.
activity_date Date[YYYY-MM-DD] The date the chargeback was issued.
transaction_currency String Three-letter ISO currency code representing the currency in which the payment was authorized.
transaction_amount String The dollar amount of the transaction that was charged back.
trxn_utc_date Date[YYYY-MM-DD] The date of the authorization in UTC.
authorization_currency String Three-letter ISO currency code representing the currency in which the payment was settled.
authorization_amount String The dollar amount of the authorization.
authorization_date Date[YYYY-MM-DD] The date of the authorization.
chargeback_amount String The dollar amount of the chargeback.
reason_code String A code that indicates the reason for the chargeback.
reason_text String A message that accompanies the reason_code.
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
bin String Bank Identification Number: first 6 digits of the credit card number used; or the 9 digits bank routing number of the bank account used.
mid String Merchant identifier for transaction processing.
epic_id String Unique identifier for the merchant.
date_reply_by Date[YYYY-MM-DD] A date by which the merchant must respond to the chargeback.
chargeback_type String The type of the chargeback.
case_id String The unique identifier for the chargeback.
date_reported Date[YYYY-MM-DD] Report date.
chargeback_currency String Three-letter ISO currency code representing the currency in which the chargeback was issued.
card_number String Credit card number.

 

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

Property Description
subscription_id String The unique identifier for the subscription.
customer_id String The unique identifier for the customer.
wallet_id String The unique identifier for the wallet used for this subscription.
terminal_id Integer The unique identifier for the terminal used for the transction.
status String The status of the subscription.
amount Decimal Transaction amount (for each transaction).
secondary_amount Decimal Secondary transaction amount (for each transaction).
last_amount Decimal Transaction amount for the final transaction.
last_secondary_amount Decimal Secondary transaction amount for the final transaction.
currency String Three-letter ISO currency code representing the currency in which the payment was authorized.
frequency String Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_days', 'every_n_weeks', 'every_n_months', or 'twice_every_month').
period Integer The number of days, weeks, or months between payments.
date_of_month_1 Integer The first payment day of each month (applicable only to subscriptions with a frequency of 'twice_every_month').
date_of_month_2 Integer The second payment day of each month (applicable only to subscriptions with a frequency of 'twice_every_month').
total_payments Integer An optional number of payments to make before the subscription expires.
alert_after Boolean Whether a notification will be sent to the consumer after each payment is made.
next_payment_date Date[YYYY-MM-DD] The date in which recurring payments will begin.
last_payment_date Date[YYYY-MM-DD] An optional date on which the subscription will expire.
epic_id String The unique identifier for the merchant account.
terminal_name String The name of the terminal used for the transaction.
accountholder String The name on the credit card or bank account used for this transaction.
account_type String Bank account types (Values: 'Visa', 'Mastercard', 'American Express', 'Discover', 'JCB', 'Diner's Club', 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
account_expiration_date String The 4-digit card expiration date in MMYY format.
customer_first_name String Customer's first name.
customer_last_name String Customer's last name.

 

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

Property Description
subscription_id String The unique identifier for the subscription.
client_order_id String A user-defined unique identifier for the Subscription.
amount Decimal Transaction amount (for each transaction).
secondary_amount Decimal Secondary transaction amount (for each transaction).
last_amount Decimal Transaction amount for the final transaction.
last_secondary_amount Decimal Secondary transaction amount for the final transaction.
frequency String Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_days', 'every_n_weeks', 'every_n_months', or 'twice_every_month').
period Integer The number of days, weeks, or months between payments.
next_payment_date Date[YYYY-MM-DD] The date in which recurring payments will begin.
last_payment_date Date[YYYY-MM-DD] An optional date on which the subscription will expire.
total_payments Integer An optional number of payments to make before the subscription expires.
wallet_id String The unique identifier for the wallet used for this subscription.
customer_first_name String Customer's first name.
customer_last_name String Customer's last name.
accountholder String The name on the credit card or bank account used for this transaction.
account_type String Bank account types (Values: 'Visa', 'Mastercard', 'American Express', 'Discover', 'JCB', 'Diner's Club', 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
account_expiration_date String The 4-digit card expiration date in MMYY format.
terminal_id Integer The unique identifier for the terminal used for the transction.
terminal_name String The name of the terminal used for the transaction.
suspend_reason String The reason this subscription is suspended.
suspend_date Date[YYYY-MM-DD] The date this subscription became suspended.

 

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

Property Description
subscription_id String The unique identifier for the subscription.
client_order_id String A user-defined unique identifier for the Subscription.
amount Decimal Transaction amount (for each transaction).
secondary_amount Decimal Secondary transaction amount (for each transaction).
last_amount Decimal Transaction amount for the final transaction.
last_secondary_amount Decimal Secondary transaction amount for the final transaction.
frequency String Whether to charge on a daily, weekly, monthly, or bi-monthly basis. (Values: 'every_n_days', 'every_n_weeks', 'every_n_months', or 'twice_every_month').
period Integer The number of days, weeks, or months between payments.
next_payment_date Date[YYYY-MM-DD] The date in which recurring payments will begin.
last_payment_date Date[YYYY-MM-DD] An optional date on which the subscription will expire.
total_payments Integer An optional number of payments to make before the subscription expires.
wallet_id String The unique identifier for the wallet used for this subscription.
customer_first_name String Customer's first name.
customer_last_name String Customer's last name.
accountholder String The name on the credit card or bank account used for this transaction.
account_type String Bank account types (Values: 'Visa', 'Mastercard', 'American Express', 'Discover', 'JCB', 'Diner's Club', 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
account_expiration_date String The 4-digit card expiration date in MMYY format.
terminal_id Integer The unique identifier for the terminal used for the transction.
terminal_name String The name of the terminal used for the transaction.
wallet_suspend_reason String The reason the wallet is suspended.
wallet_suspend_date Date[YYYY-MM-DD] The date the wallet became suspended.

 

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

Property Description
schedule_id String The unique identifier for the scheduled payment.
scheduled_date Date[YYYY-MM-DD] The transaction date for this scheduled payment.
amount Decimal Transaction amount.
secondary_amount Decimal Secondary transaction amount.
alert_after_sent Boolean Whether a notification was sent to the consumer after the transaction was completed.
alert_before_sent Boolean Whether a notification was sent to the consumer before the transaction was completed.
wallet_id String The unique identifier for the wallet used.
customer_first_name String Customer's first name.
customer_last_name String Customer's last name.
accountholder String The name on the credit card or bank account used for this transaction.
account_type String Bank account types (Values: 'Visa', 'Mastercard', 'American Express', 'Discover', 'JCB', 'Diner's Club', 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
account_expiration_date String The 4-digit card expiration date in MMYY format.
terminal_id Integer The unique identifier for the terminal used for the transction.
terminal_name String The name of the terminal used for the transaction.
subscription_id String The unique identifier for the subscription.
client_order_id String An optional user-defined unique identifier that will be associated with the Subscription.
status String The status of the scheduled payment.
transaction_id String The unique identifier for the transaction.
transaction_date Date[YYYY-MM-DD] The date of the transaction.
transaction_status String Processing status of the transaction.
response_message String A message that accompanies the transaction_status.
reason_code String Three-digit code indicates the approval status of a transaction.

 

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

Property Description
schedule_id String The unique identifier for the scheduled payment.
scheduled_date Date[YYYY-MM-DD] The transaction date for this scheduled payment.
amount Decimal Transaction amount.
secondary_amount Decimal Secondary transaction amount.
alert_after_sent Boolean Whether a notification was sent to the consumer after the transaction was completed.
alert_before_sent Boolean Whether a notification was sent to the consumer before the transaction was completed.
wallet_id String The unique identifier for the wallet used.
customer_first_name String Customer's first name.
customer_last_name String Customer's last name.
accountholder String The name on the credit card or bank account used for this transaction.
account_type String Bank account types (Values: 'Visa', 'Mastercard', 'American Express', 'Discover', 'JCB', 'Diner's Club', 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
account_expiration_date String The 4-digit card expiration date in MMYY format.
terminal_id Integer The unique identifier for the terminal used for the transction.
terminal_name String The name of the terminal used for the transaction.
subscription_id String The unique identifier for the subscription.
client_order_id String An optional user-defined unique identifier that will be associated with the Subscription.
status String The status of the scheduled payment.
transaction_id String The unique identifier for the transaction.
transaction_date Date[YYYY-MM-DD] The date of the transaction.
transaction_status String Processing status of the transaction.
response_message String A message that accompanies the transaction_status.
reason_code String Three-digit code indicates the approval status of a transaction.

 

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

Property Description
schedule_id String The unique identifier for the scheduled payment.
scheduled_date Date[YYYY-MM-DD] The transaction date for this scheduled payment.
amount Decimal Transaction amount.
secondary_amount Decimal Secondary transaction amount.
alert_after_sent Boolean Whether a notification was sent to the consumer after the transaction was completed.
alert_before_sent Boolean Whether a notification was sent to the consumer before the transaction was completed.
wallet_id String The unique identifier for the wallet used.
customer_first_name String Customer's first name.
customer_last_name String Customer's last name.
accountholder String The name on the credit card or bank account used for this transaction.
account_type String Bank account types (Values: 'Visa', 'Mastercard', 'American Express', 'Discover', 'JCB', 'Diner's Club', 'personal_checking', 'personal_savings', 'business_checking', 'business_savings')
account_suffix String Last 4 digits of the credit card number used; or last 3 digits of the bank account used.
account_expiration_date String The 4-digit card expiration date in MMYY format.
terminal_id Integer The unique identifier for the terminal used for the transction.
terminal_name String The name of the terminal used for the transaction.
subscription_id String The unique identifier for the subscription.
client_order_id String An optional user-defined unique identifier that will be associated with the Subscription.
status String The status of the scheduled payment.
transaction_id String The unique identifier for the transaction.
transaction_date Date[YYYY-MM-DD] The date of the transaction.
transaction_status String Processing status of the transaction.
response_message String A message that accompanies the transaction_status.
reason_code String Three-digit code indicates the approval status of a transaction.

 

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


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

 

Appendix 2 - Payment Types


Value Description
eCom Payfac Credit Card.
ACH Epic ACH.

 

Appendix 3 - Transaction Types


Value Description
Adjustment Manual adjustment of the merchant's balance.
Chargeback ACH chargebacks.
Credits ACH return.
Discount Processing fees.
Settlement Settlement confirmation of the merchant's balance.
Reject-CUS ACH reject triggered by customer.
Reject-MER ACH reject triggered by merchant.
Reserve Transfer of merchant balance to a reserve account.
Sale/DB Credit Card sale, ACH sale, or Debit.
MEF Month End Fee.

 

Revision History


Version Revision Date Description
1 9/17/2019 Updated Transaction Type appendix.
1 9/10/2019 Added unique_id to the deposits and deposits-detail report types.
1 6/27/2019 Fixed Active Subscriptions Report request example to show the correct URI.
1 12/14/2018 Upgrade to the Authentication Process (Api Key ID / Password)
1 2/13/2018 The transactions and balance Report Types have been removed.