Your customers have the option to utilize recurring payments with their Visa and Mastercard cards. The purpose of this operation is to enable merchants to charge for recurring services.

These types of payments are commonly used in conjunction with subscriptions for services or goods, when your customer is buying a subscription service that can be charged multiple times after the initial payment on a regular basis.

There are two types of recurring payments:

• With a pre-schedule
• Without a pre-schedule.

How it works

In the first stage the cardholder requests the payment as an initial recurring and authorize the merchant to do future debits (following recurring) accordingly with the service

Step 1: Initial payment

Action 1: Create the order

Action 2: Generate the transaction

Action 3: You can perform a Get Status

This is crucial for the cardholder to register the initial recurring payment with the merchant. To accomplish this, you need to perform three actions as outlined below.

Action 1: Create the order

The process begins when you start creating the order, adding the following recurring elements to the existing order body message.

Note that in this case you should only include “CARD” in the transaction.paymentMethod list.

Example of a request:

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments

Request Headers:

Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json

{
 "merchant": {
 "terminalId": 24,
 "channel": "web",
 "merchantTransactionId": "Order Id: uhk476ae77",
 "transactionDescription": "Recurring transaction",
 "shopURL": "https://mytest.e-shop.pl/"
 },
 "transaction": {
 "transactionTimestamp": "2023-06-09T08:38:20.680Z",
 "description": "transaction statement description",
 "moto": false,
 "paymentType": "AUTH",
 "amount": {
 "value": 50.5,
 "currency": "PLN"
 },
 "paymentMethod": [
 "CARD"
 ]
 },
 "recurringTransaction": {
 "validityDate": "2023-12-08T09:38:20.680Z",
 "amountQualifier": "DEFAULT"
 }
}

Action 2: Generate the transaction

The following request needs an Authorisation Header with the transactionSignature returned from checkout operation.

In this request, the Bearer Token is replaced by the checkout response transactionSignature.

Example of a request:

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/card/purchase

Request Headers:

Authorisation: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json

{
 "cardInfo": {
 "PAN": "5204740000001002",
 "secureCode": "100",
 "validationDate": "2025-12-31T00:00:00.000Z",
 "cardholderName": "Jane Smith",
 "createToken": false
 }
}

You should receive a successful technical response that comprises an HTTP-200 status and a returnStatus.statusCode of ‘000’.

The paymentStatus in the response informs on whether the transaction itself was accepted, declined, still pending a final result, or requiring additional action to be taken.

• Success: The purchase has been processed successfully and the customer has been debited.
• Declined: The purchase has been declined.
• Pending: The final result of the purchase is not yet known. You will need to inquiry on the status of this transaction until it reaches a final state, or you decide to cancel it.
• Partial: The purchase is partially accepted, but requires additional actions to the completed (e.g. 3D Secure authentication). The actionResponse element is provided for instructions on how to proceed.

The response should also include a recurringTransaction.status, which indicates whether the recurring setup has been successfully established. This status provides information on the correct configuration of the recurring arrangement.

Action 3: You can perform a Get Status

Once the payment has been processed, you can check the status of your transaction making a GET request.

The Authorization HTTP header is set to the Bearer token as it was used in the initial Checkout.

GET {transactionID}/status

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Request Headers:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Here are some examples of the possible result codes:

Step 2: Recurring payment

Action 1: Generate subsequent transactions

Action 2: Perform a Get Status

Action 1: Generate subsequent transactions

A Recurring Payment is used to process subsequent payments for a previously authorized initial recurring payment.

The request is performed by referencing the transactionID of the previous initial payment and sending a secure POST request over HTTPS to the /payments/{transactionID}/recurring endpoint.

POST https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/recurring

Example of a request:

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/recurring

Request Headers:

Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3 Content-Type: application/json
Content-Type: application/json

{
 "merchant": {
 "terminalId": 24,
 "channel": "web",
 "merchantTransactionId": "BO_Order Id: sar5f6ry2i"
 },
 "transaction": {
 "transactionTimestamp": "2023-06-09T07:49:45.348Z",
 "description": "Transaction short description",
 "amount": {
 "value": 50.5,
 "currency": "PLN"
 },
 "originalTransaction": {
 "id": ""
 }
 }
}

Action 2: Perform a Get Status

Once the payment has been processed, you can check the status of your transaction making a GET request.

The Authorization HTTP header is set to the Bearer token as it was used in the initial Checkout.

GET {transactionID}/status

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Request Headers:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Here are some examples of the possible result codes: