Schedule Transactions

The PayConex Sheduling Layer API (SLAPI) allows a developer to create and modify recurring payment schedules within a PayConex gateway account.

The API has four primary functions in managing recurring schedules:

1. Setting up.
2. Editing.
3. Canceling.
4. Retrieving.

When sending a request, the action parameter requires a value of SETUP, EDIT, CANCEL, or GET_DETAILS depending on the function needed. The examples below discuss each action in more detail.

API URLs

For the certification test environment:

https://cert.payconex.net/api/slapi/3.8

For the production environment:

https://secure.payconex.net/api/slapi/3.8

Scheduling Layer API Examples

Here are some key parameters that are needed in a Scheduling Layer API request and their descriptions. Tables for more request/response parameters and definitions are provided following the code examples below.

• action - This parameter tells the API which action you want to take with the API request.
• recurring_schedule - This parameter defines how often a recurring transaction is processed (monthly, daily etc...).
• recurring_payment_amount - The dollar value to be processed each time the schedule runs a transaction.
• recurring_payments_remaining - The number of times the recurring schedule will process a payment. If this value is null or empty the payment will recur indefinitely.
• start_date - The date the initial recurring transaction will start processing.
• reference_date - The date date recurring schedule can be calculated from. If not specified start_date will be used.
• status - The status of a recurring transaction. By default a new recurring setup will have a status of "ENABLED". This parameter can also be used in an edit transaction to enable/disable an existing recurring schedule.
• token_id - The value for this parameter is a transaction_id from a previous PayConex transaction. This value represents the card holder or bank account information that will be used to process the scheduled transactions.

📘

The scheduling API does not accept raw credit card numbers or bank account information within a request. Instead, a transaction must be processed through the PayConex API to get a transaction_id value. The transaction_id value is then used as the token_id parameter value within the API request to create or edit a recurring payment schedule.

Creating a Recurring Payment Schedule

The SETUP action allows for the creation of a recurring payment schedule. You can set the value of the transaction, the schedule for when the charges should occur, and the number of times you would like the recurring transaction to occur.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=SETUP \
  --data token_id=000000101101 \
  --data recurring_payment_amount=10.00 \
  --data recurring_schedule=PERIOD_1M \
  --data start_date=2021-08-12

Editing a Recurring Payment Schedule

The EDIT action will modify a recurring payment schedule with new data values provided in the API request. A valid recurring_id value must be provided.

This code example demonstrates editing of the token_id, recurring_schedule, and recurring_payment_amount values in an existing recurring schedule.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=EDIT \
  --data token_id=000000101121 \
  --data recurring_id=000000258761 \
  --data recurring_payment_amount=1.00 \
  --data recurring_schedule=PERIOD_2M

Disabling

The status parameter can be used to disable a recurring payment schedule.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=EDIT \
  --data recurring_id=000000258761 \
  --data status=DISABLED

Enabling

The status parameter can be also used to enable a recurring schedule that has been disabled.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=EDIT \
  --data recurring_id=000000258761 \
  --data status=ENABLED

Restarting a Recurring Record Marked as On-Hold

Sometimes a scheduled transaction will decline. PayConex allows a merchant to select how many times to retry recurring schedules, if all retries fail the recurring schedule will be marked as FAILED/ON HOLD. In these cases a developer may want to programmatically restart the schedule if the declines were a mistake, or after editing it with new payment info that will approve.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=EDIT \
  --data recurring_id=000000138461 \
  --data restart_billing=1

Cancelling a Recurring Payment

The CANCEL action will cancel the recurring payment schedule given a valid recurring_id value is provided. Cancelling a recurring schedule will delete the recurring schedule and removes it from the PayConex recurring schedule history.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=CANCEL \
  --data recurring_id=000000258761

Getting Recurring Schedule Details

The GET_DETAILS action will respond with the details of a scheduled recurring transaction given a valid recurring_id.

curl --request POST \
  --url https://cert.payconex.net/api/slapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data action=GET_DETAILS \
  --data recurring_id=000000134661 \
  --data response_format=JSON

SLAPI Request Format

The following table includes an index of all API requests for SLAPI.

SLAPI Response Format

The following table includes an index of all API responses for SLAPI.

📘

Did you know?

PayConex provides a webhook called POSTback. POSTback allows a developer to receive an HTTP POST after every transaction request, including recurring transactions scheduled with the Scheduling Layer API. For more information on using POSTback please see this article.

List of Recurring Schedules