The InterPay™ gateway will maintain a schedule of future payments that are to be processed. Each night any payments that have come due are automatically processed and the results sent back to the registration platform using a web callback.

The schedule can be modified (dates, amounts, add/remove future payments, etc.), suspended to stop processing of future payments, and the current status of the payments and card data can be returned.

1. Components to a Schedule

The first thing that needs to be done is to Create a Schedule. Once that is done, you must add the list of payments and the card data.

List of Payments and Card data can be added to a schedule either at the time the schedule is created or after it is created. Adding card data after the schedule is created is done through a Process Payment request (SUBTYPE=PP) or Attach Card request (SUBTYPE=AC), or using Redirect.

2. Required Fields

Request Fields for all Payment Schedule Messages

All Payment Schedule Requests will include the below fields

Response Fields for all Payment Schedule Messages

All Payment Schedule Responses will include the below fields

3. Schedule Data Block

The Schedule Data Block is a central component of the Payment Schedules feature. It is what is sent to the gateway when creating a new schedule and what is returned by the gateway when checking a schedule. It contains details about each payment schedule, and depending whether it's being sent as a Request or is a Response, can include the following:

• SCHEDID: The unique identifier for the schedule.
• PYMTS: List of payments in the schedule. Each payment in the list is delimited by [ and ] and contains the following fields:
  • DATE: The date the payment is scheduled to be processed.
  • AMT: Payment amount in dollars and cents.
  • REFNUM: Reference number for the payment; or when sent as a response, it may be blank for previous decline entries.
  • RESULT: Status of the payment (N: New (initial default), W: Waiting (added payment not yet processed), A: Approved, D: Declined, X: Archived Decline (declined moved to history), S: Stopped (deleted).
  • NOTIFY: Notification status (Y: Notified, N: Pending, E: Error).
  • CARDMASK: Masked card number used for the payment (included in Response messages)
  • RESPONSE: Text response of the transaction (included in Response messages)
• INVOICE: Invoice number tagged to the payment for reporting purposes.
• CARDMASK: Masked card number of the card currently attached to the schedule.
• CARDHASH: Hash of the card currently attached to the schedule.
• CUSTNAME: Name of the cardholder.
• CUSTEMAIL: Email address of the cardholder.
• STATUS: Status of the schedule (R: Ready, E: Card error, X: Cancelled, C: Completed, S: Suspended, N: New (needs a card attached or payments added before it can be ready)).

Example Schedule Data Block Response:

{
  "SCHEDID": "UNIQUE12345",
  "PYMTS": [
    {
      "DATE": "20241015",
      "AMT": "100.00",
      "RESULT": "A",
      "NOTIFY": "N",
      "CARDMASK": "**** **** **** 1234",    
      "RESPONSE": "APPROVED"
    }
  ],
  "INVOICE": "INV001",
  "CARDMASK": "**** **** **** 1234",
  "CUSTNAME": "John Doe",
  "CUSTEMAIL": "[email protected]",
  "STATUS": "R",
}

4. Creating a New Schedule

Purpose: To create a new payment schedule.

Requests

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (CS to create a schedule), a unique identifier for the schedule (SCHEDID), and the Invoice Number (INVOICE ) for the schedule.

To add additional details to the transaction, you may include the DESC parameter.

Attach Card Data

The minimum required information to attach card data at the time you are creating the new schedule includes the Card Number (CARD ) and Expiry Date (EXP), and the Customer Name (CUSTNAME) and Customer Email Address (CUSTEMAIL).

ℹ️

If you do not attach card data when creating the schedule, you can attach it at a later time using PP or AC requests.

Attach Payments (PYMTS)

Payments can be added when creating the schedule, or later. PYMTS is a list of all the payments attached to a schedule and is built by appending each payment, with each payment consisting of the following required fields surrounded by [ ]: the date the payment should be processed (DATE), the amount of the payment (AMT), and and a unique Reference Number (REFNUM).

Example request:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "SCHEDID": "A1234-5678-123"
  "SUBTYPE": "CS",
  "INVOICE": "INV001",
  "DESC": "Monthly Subscription",
  "PYMTS": [
    {
      "DATE": "20241015",
      "AMT": "100.00",
      "REFNUM": "12345",   
    }
  ]
}

5. Attaching or Updating Card Data

Purpose: To attach or update card data for an existing schedule.

Requests

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (AC to attach card), the schedule identifier (SCHEDID), the Card Number (CARD ) and Expiry Date (EXP), and the Customer Name (CUSTNAME) and Customer Email Address (CUSTEMAIL).

Alternatively, you may choose to attach Tokenized Card Data (TOKEN) instead of the CARD and EXP.

Example request to attach or update card data:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "SUBTYPE": "AC",
  "SCHEDID": "UNIQUE12345",
  "CARD": "4111111111111111",
  "EXP": "1230",
  "CUSTNAME": "John Doe",
  "CUSTEMAIL": "[email protected]"
}

6. Processing Scheduled Payments

Purpose: To process a payment immediately rather than waiting for the scheduled date.

Often a payment should be processed at the same time the schedule is created. This can be done either through a direct call to the host or by using a web-redirect which also collects and attaches card data from the customer as part of the process.

For Host-Based, the payment is attempted using either the card data already attached to the schedule or by specifying new card data which will then become attached to the schedule.

If the payment is declined then the schedule will be placed in the E (card error) STATUS and further action is needed.

This action will provide a response message and will also trigger a callback notification the same way as if it had been processed by the scheduler. If the NOTIFY status of the returned schedule data is N keep in mind that the callback may have been delayed compared to the actual processing of the payment.

Any payments with a STATUS of W or D can be sent for processing regardless of date. This means that declined payments can be attempted again. Each time a declined payment is processed another entry is added to the payment list with a STATUS of X and blank REFNUM.

Requests

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (PP to process payment), the schedule identifier (SCHEDID), and the Reference Number (REFNUM) of the payment in the schedule that you are processing immediately.

Process Scheduled Payment with New Card Data

Include these fields in the Process Payment (PP) request if a new card is to be attached prior to processing the payment, otherwise the existing attached card will be used: the Card Number (CARD ) and Expiry Date (EXP), and the Customer Name (CUSTNAME) and Customer Email Address (CUSTEMAIL).

7. Suspend, Restore, or Cancel Schedule

Schedules can be Suspended (SS for Suspend Schedule), Restored (SR for Schedule Restore, and Cancelled (SC for Schedule Cancel).

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (SS , SR, or SC) and the schedule identifier (SCHEDID),

Example request:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "SUBTYPE": "SS",
  "SCHEDID": "UNIQUE12345"
}

8. Adding, Updating, or Removing Payments

Schedules can be modified by adding additional payments, changing the date or amount of a payment, or removing a payment.

Payments that have already been processed and approved (A result) cannot be updated or removed. Removing all the remaining payments from a schedule will change its STATUS to C (complete). Conversely, adding a payment to a completed schedule will change its STATUS to R (ready).

Below are the subtypes:

• PU: Update Payment: Change the date and/or amount of a payment
• PA: Add Payment: Add additional payment to the schedule
• PR: Remove Payment: Remove a payment from the schedule

Attach Payment

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID (TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (PA for payment attach), the schedule identifier (SCHEDID), the date of the payment (DATE ), the amount of the payment (AMT), and the reference number for the payment (REFNUM), which, if omitted or left blank, will be automatically assigned by the gateway.

Example request for adding a payment:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "TYPE": "L",
  "SUBTYPE": "PA",
  "SCHEDID": "UNIQUE12345",
  "DATE": "20241020",
  "AMT": "5000",
  "REFNUM": "67890"
}

Update Payment

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID (TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (PU for payment update), the schedule identifier (SCHEDID), the date of the payment (DATE ), the amount of the payment (AMT), and the reference number for the payment (REFNUM).

If you are changing the date of the payment, also include the new date for the payment (DATE).

If you are changing the amount of the payment, also include the new amount for the payment (AMT).

Example request for updating a payment:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "TYPE": "L",
  "SUBTYPE": "PU",
  "SCHEDID": "UNIQUE12345",
  "DATE": "20241120", //Including Date field as the date of the payment is being changed
  "AMT": "10000", //Including Amount field as the amount of the payment is being changed
  "REFNUM": "67890"
}

Remove Payment

The Payment Schedule API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID (TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (PR for payment remove), the schedule identifier (SCHEDID), and the reference number for the payment (REFNUM).

Example request for removing a payment:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "TYPE": "L",
  "SUBTYPE": "PR",
  "SCHEDID": "UNIQUE12345",
  "REFNUM": "67890"
}

9. Get Schedule Status

In order to ensure synchronization of schedules between the platform and the InterPay™ gateway, the status of a schedule (including details of all the payments and the currently attached card data) can be retrieved at any time.

The required information for this request includes the merchants Terminal ID (TERMID) and Password (PASS), the type of transaction (L for Payment Schedule Activity), the subtype (GS for get status), and the schedule identifier (SCHEDID).

Example request for get schedule status:

{
  "TERMID": "TEST0005",
  "PASS": "PASS1234",
  "TYPE": "L",
  "SUBTYPE": "GS",
  "SCHEDID": "UNIQUE12345",
}

10. Notification Payload

You will provide us with a URL for where all payment schedule activity notifications be can sent. This allows the platform to react to scheduled activity by updating the customer’s account, maintaining a local copy of the schedules, react to declines, etc.

When your platform receives the notification, it should respond to the gateway with a HTTP status of 200 and a response in the body.

Payment Processed Notification

Every time the gateway processes a scheduled payment, the details of what happened are sent to the platform as a notification message.

• Fields:
  • TERMID: Terminal ID that triggered the notification.
  • TYPE: Notification type (N: Notification).
  • SUBTYPE: SP (Scheduled Payment).
  • SCHEDID: Schedule ID of the payment.
  • INVOICE: Invoice number tagged to the payment.
  • REFNUM: Reference number of the payment.
  • APPROVED: Y for approved, N for not approved.
  • RESPONSE: Text response of the transaction.
  • SCHEDULEDATA: Contains the Schedule Data Block, providing information about the schedule associated with the notification.
    • PYMTS: List of payments in the schedule. Each payment in the list is delimited by [ and ] and contains the following fields:
      • DATE: The date the payment is scheduled to be processed.
      • AMT: Payment amount in dollars and cents.
      • REFNUM: Reference number for the payment; or when sent as a response, it may be blank for previous decline entries.
      • RESULT: Status of the payment (N: New (initial default), W: Waiting (added payment not yet processed), A: Approved, D: Declined, X: Archived Decline (declined moved to history), S: Stopped (deleted).
      • NOTIFY: Notification status (Y: Notified, N: Pending, E: Error).
      • CARDMASK: Masked card number used for the payment (included in Response messages)
      • RESPONSE: Text response of the transaction (included in Response messages)
    • INVOICE: Invoice number tagged to the payment for reporting purposes.
    • CARDMASK: Masked card number of the card currently attached to the schedule.
    • CARDHASH: Hash of the card currently attached to the schedule.
    • CUSTNAME: Name of the cardholder.
    • CUSTEMAIL: Email address of the cardholder.
    • STATUS: Status of the schedule (R: Ready, E: Card error, X: Cancelled, C: Completed, S: Suspended, N: New (needs a card attached or payments added before it can be ready)).

Platform Response to Notification

Platforms must respond to the notifications. The response is either OK if the notification is accepted or a short error message if the notification is not accepted.

Example notification response:

{
  "TERMID": "TEST0058",
  "TYPE": "N",
  "SUBTYPE": "SP",
  "SCHEDID": "UNIQUE12345",
  "INVOICE": "INV001",
  "REFNUM": "12345",
  "APPROVED": "Y",
  "RESPONSE": "Payment Approved",
  "SCHEDULEDATA": {
    "SCHEDID": "UNIQUE12345",
    "PYMTS": [
      {
        "DATE": "20241015",
        "AMT": "100.00",
        "RESULT": "A",
        "NOTIFY": "Y",
        "CARDMASK": "**** **** **** 1234",
        "CUSTNAME": "John Doe",
        "CUSTEMAIL": "[email protected]",
        "INVOICE": "INV001",
        "RESPONSE": "Payment Approved"
      }
    ],
    "STATUS": "R"
  }
}

11. Managing Declined Payments

Declined payments are archived and can be managed through retries or removals. The status of a payment indicates its outcome:

• D: Declined.
• X: Archived Decline (a decline moved to history)
• S: Stopped (deleted).