Skip to main content
Version: 1.0.0

Recurring Schedules API

A schedule sets how often and how many times Payment Platform charges a subscription by itself: the interval, the number of payments and an optional delay of the first payment. You attach a schedule to an initial recurring payment, and Payment Platform then creates the later payments by that schedule.

Not tied to a protocol​

These requests do not depend on Protocol Mapping. A merchant can send them whatever protocols are enabled for it, including a merchant whose only active protocol is Checkout. You do not need an S2S CARD protocol mapping to create or manage schedules.

STOP_SCHEDULE is not part of this group. It asks the payment provider to stop a schedule that the provider runs, and it is an S2S CARD request that needs an enabled S2S CARD protocol mapping: see Stop Provider Schedule.

Requests​

RequestactionWhat it does
Create ScheduleCREATE_SCHEDULECreates a new schedule and returns its schedule_id
Update ScheduleUPDATE_SCHEDULEUpdates an existing schedule. Only the parameters sent in the request are updated
Pause SchedulePAUSE_SCHEDULESuspends the scheduled payments associated with the schedule and sets paused to Y
Run ScheduleRUN_SCHEDULEReleases a schedule paused with PAUSE_SCHEDULE and sets paused to N
Delete ScheduleDELETE_SCHEDULEDeletes a schedule that no payment uses. A schedule that payments already use is not deleted
Schedule InfoSCHEDULE_INFOReturns the details of an existing schedule
DescheduleDESCHEDULEStops the scheduled payments of one subscription, the one of the recurring_token sent in the request. Other subscriptions on the same schedule continue

The parameters of each request are on its page, and the same requests are described with examples in Recurring schedule operations.

Endpoint and format​

Send every request by POST to {PAYMENT_URL}/post, form-encoded (Content-Type: application/x-www-form-urlencoded). This is the API endpoint described in Authentication and credentials, not the Checkout session endpoint. The response is JSON.

client_key is your merchant key, the same value you send as merchant_key in Checkout requests.

Signature​

actionFormula
CREATE_SCHEDULEFormula 3: md5(strtoupper(strrev(PASSWORD)))
UPDATE_SCHEDULE, PAUSE_SCHEDULE, RUN_SCHEDULE, DELETE_SCHEDULE, SCHEDULE_INFO, DESCHEDULEFormula 4: md5(strtoupper(strrev(schedule_id + PASSWORD)))

PASSWORD is the merchant Password from the admin panel, see Which password the formulas mean.

The digest is MD5 or SHA256 depending on the Use SHA256 encryption algorithm for hash option of the merchant's S2S CARD protocol mapping, also when that mapping is not enabled. A merchant with no S2S CARD protocol mapping signs these requests with MD5, even if the option is enabled for its Checkout protocol mapping. See Recurring schedule signatures.

Using a schedule in a payment​

Send the schedule_id in the initial recurring payment:

Payment Platform then creates the later payments by the schedule, with no further requests from you. Each of them produces its own callback. The schedule data in the callbacks is listed in Checkout callback parameters and S2S CARD callback parameters.

A schedule can also be created in the admin panel. Its schedule_id is used the same way.

Stopping the scheduled payments​

  • One subscription: DESCHEDULE with the recurring_token of the initial recurring payment and the schedule_id. This works the same for a subscription started over Checkout, where the recurring_token comes in the callback of the initial payment.
  • Every subscription on a schedule, for a while: PAUSE_SCHEDULE, then RUN_SCHEDULE to resume.
  • In the admin panel: see Stopping a subscription.