Recurring Payments
Introduction
In cases where a one-off payment is not sufficient, such as a recurring monthly subscription or a payment split across a number of months, our recurring payment features can be used.
Payments API
Also known as recurring payments, it is possible to set up a subscription payment via our APIs using the [payment-schedule](ref:createpaymentschedule) endpoint.
1. Creating the subscription
Firstly, to start a new subscription, you must perform a POST providing all the necessary details about the subscription such as:
startDate- the date the payments should beginnumberOfPayments- the total number of payments that will be taken over the course of the subscriptionfrequency- how often the payments will be taken
Click for example request / response
See the example request and response for this here:
{
"requestType": "PaymentMethodPaymentSchedulesRequest",
"startDate": "2023-01-01",
"numberOfPayments": 11,
"maximumFailures": 1,
"invoiceNumber": "INV1234",
"purchaseOrderNumber": "PO1042",
"transactionOrigin": "ECOM",
"dynamicMerchantName": "A really cool merchant",
"frequency": {
"every": 1,
"unit": "MONTH"
},
"paymentMethod": {
"paymentCard": {
"number": "1234123412341234",
"expiryDate": {
"month": "01",
"year": "28"
},
"securityCode": "123"
}
},
"transactionAmount": {
"total": "20.99",
"currency": "EUR"
}
}
{
"clientRequestId": "6e9e3521-ef4e-4598-94c5-83e3ce07ed03",
"apiTraceId": "YzQkrsQq0Q2umBxuy6d4cQAAAvU",
"requestStatus": "SUCCESS",
"orderId": "R-79ae2b06-78b2-4d8b-9640-c379a5b6420f",
"state": "Installed"
}
2. Managing the subscription
Once a payment schedule has been established, there are then 3 actions that can be taken on it:
- View the schedule to see how it is progressing
- Update the schedule, for example to adjust the amount to be paid
- Cancel the schedule, preventing all future payments
For example, if we want to view an existing subscription, we would use the orderId returned in the above response.
Click for example response
See the example response for this here:
// GET /payment-schedules/R-79ae2b06-78b2-4d8b-9640-c379a5b6420f
{
"clientRequestId": "85b51979-e291-42f7-a2a5-4fa712297926",
"apiTraceId": "YzQ7X5pRN-z9R2q7VM8EawAAAXg",
"orderId": "R-79ae2b06-78b2-4d8b-9640-c379a5b6420f",
"transactions": [],
"recurringPaymentDetails": {
"storeId": "72305408",
"purchaseOrderNumber": "PO1042",
"invoiceNumber": "INV1234",
"creationDate": "Wed Sep 28 14:19:25 CEST 2022",
"startDate": "Sun Jan 01 00:00:00 CET 2023",
"nextAttemptDate": "Sun Jan 01 00:00:00 CET 2023",
"creationDateFormatted": "2022-09-28",
"startDateFormatted": "2023-01-01",
"nextAttemptDateFormatted": "2023-01-01",
"transactionAmount": {
"total": 20.99,
"currency": "EUR",
"components": {
"subtotal": 20.99
}
},
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "10",
"year": "45"
},
"last4": "1002"
},
"paymentMethodType": "PAYMENT_CARD"
},
"frequency": {
"every": 1,
"unit": "MONTH"
},
"numberOfPayments": 10,
"runCount": 0,
"state": "Installed"
}
}
Example complete!
The same principles apply in using
orderIdto update or cancel an existing subscription.
Hosted Payment Page
Recurring payments can either be triggered by your system every time a payment is due or you can make use of our scheduler that allows you to define the frequency and period (e.g. every three days, every second week, every month, once a year, etc.)
To use this feature, the following additional parameters will have to be submitted in the initial transaction request form:
| Field Name | Available Values | Description |
|---|---|---|
recurringInstallmentCount | numeric; min 2 max 999 | Represents the number of installments to be made including the initial transaction submitted |
recurringInstallmentPeriod | • day • week • month • year | Represents the periodicity of the recurring payment |
recurringInstallmentFrequency | numeric: min 1 max 99 | Represents the time period between installments |
NOTE
Please note, that the start date of the recurring payments will be the current date and will be automatically calculated by the system.
Updated 3 months ago
