Menu

Recurring

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.

Data elementTypeConditionDescription
recurringTransactionInputRecurringTransactionMandatoryObject that defines a recurring transaction request. Only present for Recurring Transactions.
validityDateisoDateTimeMandatoryDate of the validity of the recurring transaction.
amountQualifierStringMandatoryQualifier of the recurring transaction amount.
descriptionStringOptionalDescription of the recurring transaction.
scheduleScheduleOptionalRecurring Transaction Schedule.
initialDateisoDateTimeOptionalRecurring Transaction Start Date Time.
finalDateisoDateTimeOptionalRecurring Transaction End Date Time.
intervalIntervalTypeOptionalRecurring Transaction Frequency.
Possible values are (
“DAILY”,
“WEEKLY”,
“BIWEEKLY”,
“MONTHLY”,
“QUARTERLY”,
“SEMIANNUAL”,
“ANNUAL” ).

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

Example of a request:

Run in Postman

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:

Run in Postman

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
Run in Postman

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:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many Requests
The API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

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:

Run in Postman

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
Run in Postman

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:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many Requests
The API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

On this page: