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 begin
  • numberOfPayments - the total number of payments that will be taken over the course of the subscription
  • frequency - 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 orderId to 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 NameAvailable ValuesDescription
recurringInstallmentCountnumeric; min 2 max 999Represents the number of installments to be made including the initial transaction submitted
recurringInstallmentPeriod• day
• week
• month
• year
Represents the periodicity of the recurring payment
recurringInstallmentFrequencynumeric: min 1 max 99Represents 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.


Want a quick overview?