Recurring Payment

Overview.

Paylink offers a straightforward and secure solution for managing recurring payments for your business. Our platform features easy-to-use endpoints, enabling you to initiate or cancel recurring payments and to view all active regular payments. This functionality mainly benefits business models based on subscriptions, where traditional, automated billing is essential.

How it works

In the registerPayment endpoint of our API, you need to modify the recurringModel parameter to enable recurring payments, which returns a recurringId to your system for tracking.

The iteration parameter controls the frequency of charges to the customer for your services. Setting this parameter to "0" allows indefinite billing cycles until the recurring payment is canceled.

The recurringType parameter specifies the interval for repeated charges with the same amount as defined in the registerPayment endpoint request. The possible values for this parameter are:

  • Custom
  • Daily
  • Weekly
  • Monthly

Selecting any option except "Custom" will disregard the intervalDays parameter. Conversely, if "Custom" is chosen for recurringType, you must set the intervalDays parameter to a value between 1 and 180 days, depending on your business requirements.

Additionally, the retryCount parameter is available to determine how many attempts should be made to process a failed recurring payment before terminating the subscription. This is an optional parameter that can be set between 0 to 5. The system retries the payment daily until the count reaches zero or the payment is successful. With each new billing cycle, the retry count is reset.

Environment

Paylink has two environments which are testing and production environments. The base server link of both environments are:

📘

Testing:

The testing server base is https://restpilot.paylink.sa.

📘

Production:

The production server base is https://restapi.paylink.sa.

Authentication

This endpoint requires authentication using a bearer token provided by RestPilot Paylink. The token should be included in the Authorization header of the request.

Endpoint

POST /api/registerPayment

Request Headers

HeaderRequiredDescription
AuthorizationYesBearer token provided by Authentication Endpoint
AcceptYesIt must be set to application/JSON.
Content-TypeYesIt must be set to application/JSON.
{
  "Authorization": "Bearer [id_token]",
  "Accept": "application/json",
  "Content-Type": "application/json"
}

Request Body Parameters

Example of the body request:

{
  "payment": {
    "value": 100.00,
    "currencyCode": "SAR",
    "paymentNote": ""
  },
  "customer": {
    "name": "customer name",
    "mobile": "0512345678",
    "email": "[email protected]"
  },
  "urls": {
    "callback": "https://google.com"
  },
  "recurring": {
    "type": "Custom",
    "intervalDays": 1,
    "iterations": 3,
    "retryCount": 5
  }
}

Response Example

{
  "response": {
    "isSuccess": true,
    "message": "Recurring Payment Regsitered Successfully!",
    "validationErrors": null
  },
  "invoiceDetails": {
    "paymentUrl": "https://paymentpilot.paylink.sa/pay/info/030631666083046",
    "customerReference": null,
    "userDefinedField": null,
    "recurringId": "RP0306316"
  }
}