Schedule Transactions

A guide on using the Scheduling Layer API to create recurring payments

This guide explains how to utilize the PayConex scheduling layer API (SLAPI). This API allows a developer to create and modify recurring schedules within a PayConex gateway account.

The API has four primary functions; setting up, editing, canceling, and retrieving recurring schedules. When sending a request the action parameter is required with a value of SETUP, EDIT, CANCEL, or GET_DETAILS depending on the function needed. The examples below will 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.

In this code example I am editing 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 also 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 opposite is also true, the status parameter can be 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 deletes 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 request for SLAPI.

Variable Name Max Type Req'd Description
account_id 12 numeric Yes This is the Payconex account identification number that you are issued after your account has been set up.
action 11 enumerated Yes SETUP, EDIT, CANCEL, GET_DETAILS
api_accesskey 32 text Yes This is a secret key that you will be provided when your Payconex account is set up and when you’ve requested access to QSAPI.
description 65K Character No A description of the payment. This is an open field. If emails are sent to the customer or merchant, this will show in the “Description:” field. You may use this to send any information that you wish.
label 50 text No If not sent, label will be generated automatically (first name + last name + unique ID, space permitting). Used for display in Payconex.

Optional: EDIT
Not allowed: SETUP, GET_DETAILS, CANCEL
recurring_id 12 numeric Yes/No This is the recurring ID, from an existing recurring schedule.

Required: EDIT, CANCEL, GET_DETAILS
Not allowed: SETUP
recurring_payment_amount 9 numeric with decimal Yes/No Amount for this payment.

Required: SETUP
Optional: EDIT
Not allowed: GET_DETAILS, CANCEL
recurring_payments_remaining 5 numeric No Number of recurring payments remaining. 0 means no scheduled payments remain. NULL (empty) means payment recurs forever.

Optional: EDIT, SETUP
Not allowed: GET_DETAILS, CANCEL
recurring_schedule enumerated Yes/No See list of acceptable values in Appendix A.

Required: SETUP
Optional: EDIT
Not allowed: GET_DETAILS, CANCEL
reference_date 10 date (YYYY-MM-DD) Varies Date recurring schedule is calculated from. If not specified start_date will be used.
response_format enumerated No Desired response format.
FORM: www-form-urlencoded (default)
JSON: JavaScript Object Notation
DEBUG: Human readable array output
restart_billing 1 boolean No Allows a restart of an "on hold" recurring transaction record. Value of 1 can be used in EDIT with recurring_id to restart schedule.

Optional: EDIT
Not allowed: SETUP, GET_DETAILS, CANCEL
start_date 10 date Yes/No Date of first recurring payment.

Required: SETUP
Optional: EDIT
Not allowed: GET_DETAILS, CANCEL
status 8 enumerated No Either ENABLED or DISABLED

Default for SETUP is ENABLED
Optional: EDIT
Not allowed: CANCEL, GET_DETAILS
token_id 12 numeric Yes/No This is the token ID from a QSAPI STORED transaction.

Required: SETUP
Optional: EDIT
Not allowed: GET_DETAILS, CANCEL

SLAPI Response Format

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

Variable Name Max Type Description
description 65K Character The same variable submitted in the request.
label 50 text Used for display in Payconex. Originates from the QSAPI variable "custom_id"
next_recurring_payment_date 10 date (YYYY-MM-DD) Date of the next recurring payment.
recurring_id 12 numeric Use this to EDIT or CANCEL a recurring entry.
recurring_payment_amount 9 numeric with decimal Amount charged on next recurring payment date
recurring_payments_remaining 3 numeric Number of recurring payments remaining. 0 means no scheduled payments remain. NULL (or empty) means payment will recur forever.
recurring_schedule enumerated See list of possible values in Appendix A.
recurring_schedule_description text Human-readable form of recurring schedule. E.g., “First Monday of every month” or “Every Friday”
start_date 10 date (YYYY-MM-DD) Date of first recurring payment.
status 8 enumerated ENABLED: Payment will recur as scheduled.
DISABLED: Payment has been disabled and will not recur.
CANCELED: Recurring payment has been stopped and will not recur.
RETRYING: Payment failed and will retry up to the number of times in your account's settings.
FAILED: Payment failed and will not be retried.
FINISHED: No more recurring payments remain.
token_id 12 numeric This is the token from a QSAPI STORED transaction.

📘

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

Recurring Schedule Description Uses Period Date?
PERIOD_1W Once a Week Yes
PERIOD_2W Every 2 Weeks (Bi-Weekly) Yes
PERIOD_1M Once a Month Yes
MONTHLY_1_15 1st and 15th of every month No
MONTHLY_5_20 5th and 20th of every month No
MONTHLY_LAST Last day of every month No
PERIOD_2M Every 2 Months Yes
PERIOD_3M Every 3 Months Yes
QUARTERLY_1 First day of every Quarter No
QUARTERLY_LAST Last day of every Quarter No
PERIOD_6M Every 6 Months Yes
PERIOD_1Y Once a Year Yes
YEARLY_Q1_1 Annually, every quarter 1 on the 1st No
YEARLY_Q2_1 Annually, every quarter 2 on the 1st No
YEARLY_Q3_1 Annually, every quarter 3 on the 1st No
YEARLY_Q4_1 Annually, every quarter 4 on the 1st No

Did this page help you?