Recurring Payments API

Initiate a recurring payment for a customer who has completed an initial transaction through the hosted payment page.

Authentication Required

All Direct API requests require HMAC signature authentication. Please refer to the API Authentication guide for detailed instructions.

Payment Flow for Recurring Transactions

The merchant redirects the customer to the Cycle hosted payment page to complete the initial transaction. See the Hosted Payment Page Guide for implementation details.
Once the initial transaction is successfully completed, the merchant receives a server-to-server notification containing the PaymentProfileId, which can be used for future recurring charges.
To initiate a recurring payment, the merchant calls the Charge API, passing the stored storedPaymentProfileId as the payment method.
The Cycle platform processes the request, returns the result, and sends a server-to-server notification to the merchant with the outcome.

Submit a Recurring Charge

Endpoint

POST /api/v3/charges

Request Parameters

Field	Required	Description
`command`	Yes	Fixed as “CHARGE”
`id`	Yes	1-100 chars, letter, number and hyphen are allowed. The unique transaction ID specified by the merchant.
`customer.id`	Yes	Customer ID specified by the merchant.
`lineItem.currency`	Yes	Currency ISO code (e.g. ZAR)
`lineItem.amount`	Yes	The amount to collect
`lineItem.description`	Yes	The product’s description. 1-100 chars
`payment.storedPaymentProfileId`	Yes	PaymentProfile Id that was provided in response to the INITIAL charge request.
`payment.countryCode`	Yes	Fixed as “ZA”
`recurrence.type`	Yes	Fixed as “RENEWAL”. It’s used to signify the subsequent recurring transaction for recurring flow.

Example Request

{
 "command": "CHARGE",
 "id": "txn_recurring_demo_001",
 "customer": {
   "id": "TestUserRec"
 },
 "lineItem": {
   "currency": "ZAR",
   "amount": 12.7,
   "description": "Monthly Subscription"
 },
 "payment": {
   "storedPaymentProfileId": "spp_12345abcde67890",
   "countryCode": "ZA"
 },
 "recurrence": {
   "type": "RENEWAL"
 }
}

Example Response

A successful recurring charge will have a `status` of "CHARGED".

{
   "id": "txn_recurring_demo_001",
   "internalId": "cyc_rec_abc123",
   "status": "CHARGED",
   "merchantAccount": "CycleDemo",
   "lineItem": {
       "amount": 12.7,
       "currency": "ZAR",
       "description": "Monthly Subscription"
   },
   "transactions": [
       {
           "timestamp": "2024-10-28T10:00:00Z",
           "gatewayProvidedId": "gateway_rec_txn_123",
           "type": "CHARGE",
           "state": "APPROVED",
           "amount": 12.7,
           "currency": "ZAR",
           "resultCode": 0,
           "responseText": "Success"
       }
   ],
   "paymentType": "CREDIT_CARD",
   "paymentMethod": "VISA",
   "created": "2024-10-28T09:59:58Z"
}

Direct API Guide

Payment Links