Recurring Payments allow merchants to process future payments using payment credentials previously authorized by the customer during an initial Cardholder-Initiated Transaction (CIT). 

Recurring Payments are typically used for subscription-based services or recurring billing scenarios where charges are processed at predefined intervals. 

During the initial CIT, the recurring agreement is established by defining the recurring payment configuration, including the billing schedule. After the initial payment is successfully completed, all subsequent recurring charges are automatically processed by SIBS Gateway as Merchant-Initiated Transactions (MITs), using the stored payment credentials and the original CIT transaction reference. 

The merchant is only required to configure the recurring agreement during the initial payment. Once the agreement is established, SIBS Gateway manages the execution of all subsequent recurring payments according to the configured schedule. 

When to use Recurring 

Use this model when the merchant charges the customer on a fixed and predictable schedule, such as: 

• Monthly or annual subscriptions 
• SaaS billing cycles 
• Membership fees 
• Periodic payments (fixed or variable) with a known billing interval 

How it Works 

Recurring Payments are implemented in three  steps. 

• Step 1 – Initial Cardholder-Initiated Transaction (CIT) 
• Step 2 – Subsequent Merchant-Initiated Transactions (MIT)  
• Step 3 – Receive Payment Notifications (Optional)

Step 1 – Initial Cardholder-Initiated Transaction (CIT) 

The customer performs the initial payment. 

During this transaction, the merchant establishes the recurring agreement by configuring the Merchant-Initiated Transaction (MIT) parameters. 

Once the initial transaction has been successfully completed, SIBS Gateway generates an original-tx-id, which uniquely identifies the recurring agreement and must be referenced by all future Merchant-Initiated Transactions. 

This step consists of the following actions: 

• Action 1 – Create the Order 
• Action 2 – Process the Payment 
• Action 3 – Get Transaction Status (Optional) 

Action 1 – Create the Order 

Start by creating a standard payment order using the Checkout Payment API. 

For the complete request structure, required headers and standard payment fields, refer to the Create Order section of the API Integration documentation. 

When creating the initial CIT, include the MIT configuration fields described in the table below. These fields determine that the transaction establishes a recurring agreement and define how future recurring payments will be processed. 

Endpoint URL: 

API	Operation
Checkout Payment API	POST /api/{version-id}/payments

MIT Configuration Fields 

Field	Type	Condition	Description	Example
Request Body .merchantInitiatedTransaction	MITTypeCode	Optional	Defines the Merchant-Initiated Transaction type. For recurring payments, set this field to RCRR. Possible values: RCRR, UCOF.	“RCRR”
Request Body .recurringTransaction	RecurringTransaction	Conditional	Object that defines the recurring agreement. Required when merchantInitiatedTransaction is set to RCRR.	{…}
Request Body .recurringTransaction.validityDate	isoDateTime	Optional	Date until which the recurring agreement remains valid.	“2027-12-31T23:59:59Z”
Request Body .recurringTransaction.amountQualifier	String	Optional	Qualifies the recurring payment amount. Possible values are ACTUAL, ESTIMATED and DEFAULT. If omitted, DEFAULT is assumed.	“DEFAULT”
Request Body .recurringTransaction.description	String	Optional	Description of the recurring agreement.	“Monthly Subscription”
Request Body .recurringTransaction.schedule	Schedule	Optional	Defines the recurring payment schedule. If omitted, future recurring payments must be initiated by the merchant using the MIT API.
Request Body .recurringTransaction.schedule.initialDate	isoDateTime	Conditional	Start date of the recurring schedule. Required when configuring scheduled recurring payments.	“2026-08-01T00:00:00Z”
Request Body .recurringTransaction.schedule.finalDate	isoDateTime	Conditional	End date of the recurring schedule. Required when configuring scheduled recurring payments.	“2027-08-01T00:00:00Z”
Request Body .recurringTransaction.schedule.interval	IntervalType	Conditional	Defines the recurring payment frequency. Possible values are DAILY, WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL and ANNUAL. Required when configuring a recurring schedule.	“MONTHLY”
Request Body .recurringTransaction.hideNonRecurring	Boolean	Optional	Indicates whether non-recurring payment methods should be hidden during checkout. If omitted, the default value is false.	true

Example Request 

The following example shows a complete Checkout Payment request configured to create a Recurring agreement. During this initial Cardholder-Initiated Transaction (CIT), the merchant defines the recurring configuration that will be used for subsequent Merchant-Initiated Transactions (MIT). 

</> JSON 
 
{ 
    "merchant": { 
        "terminalId": {{TerminalID}}, 
        "channel": "web", 
        "merchantTransactionId": "{{merchantTrxID}}", 
        "websiteAddress": "https://website.com" 
    }, 
    "customer": { 
        "customerInfo": { 
            "customerLanguage": "pl" 
        } 
}, 
    "transaction": { 
        "transactionTimestamp": "{{trxDatetime}}", 
        "description": "Transaction for order number {{trxOrderNum}} terminalId {{TerminalID}}", 
        "moto": false, 
        "paymentType": "AUTH", 
        "amount": { 
            "value": 50.50, 
            "currency": "PLN" 
        }, 
        "paymentMethod": [ 
            "CARD" 
        ] 
    }, 
    	"tokenisation": { 
"tokenisationRequest": { 
"tokeniseCard": false 
}, 
"paymentTokens": [] 
}, 
    "merchantInitiatedTransaction": "RCRR", 
    "recurringTransaction": { 
        "validityDate": "{{trxRecurrValidityDatetime}}", 
"amountQualifier": "DEFAULT", 
        "description" : "Recurring transaction -> Order {{trxOrderNum}}", 
        "schedule" : { 
            "initialDate": "{{trxRecurrInitialDatetime}}", 
            "finalDate": "{{trxRecurrFinalDatetime}}", 
            "interval": "MONTHLY" 
        } 
    } 
} 

Action 2 – Process the Payment 

Once the order has been created, complete the customer payment using the Card Purchase API. 

Unlike the Checkout request, this operation does not use the Bearer Token in the Authorization header. Instead, the request must include the transactionSignature returned in the Checkout response. 

The transactionSignature authorizes the payment execution for the transaction previously created through the Checkout API. 

API	Operation
Card Purchase API	POST /api/{version-id}/payments/{transactionID}/card/purchase

Header Parameters

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Use transactionSignature returned by the Checkout API. This request must use the Digest authentication scheme.	Digest {transactionSignature}
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Example Purchase Request:

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

Response 

A successful technical response returns: 

• HTTP Status 200  
• returnStatus.statusCode = “000”  

The paymentStatus indicates the outcome of the payment authorization.

Payment Status	Description
Success	The payment was successfully authorized and the recurring agreement was established.
Declined	The payment was declined. No recurring agreement is created.
Pending	The final payment result is not yet available. Use the Status API until a final status is returned.
Partial	Additional customer interaction is required (for example, 3DS authentication). The actionResponse element is provided for instructions on how to proceed.

The API response also includes the recurringTransaction.status field. This field confirms whether the recurring agreement has been successfully created and is eligible for future automatic recurring executions. Only when this status is successful can the transaction be used as the reference for future Recurring Merchant-Initiated Transactions (MIT). 

Action 3 – Get Transaction Status (Optional) 

After the payment has been submitted, you can verify its processing status using the Status API. 

Unlike the Card Purchase request, the Status API uses the same authentication method as the initial Checkout request. The Authorization header must contain the Bearer Token. 

Endpoint URL 

API	Operation
Payment Status API	GET /api/{version-id}/payments/{transactionID}/status

Header Parameters

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Example Request

Checkout Status Response 

A successful technical response returns HTTP 200 with returnStatus.statusCode = “000”. 

Use this operation whenever you need to retrieve the latest processing status of the transaction. 

For a complete list of transaction status codes, error codes and decline reasons, refer to the Error Handling & Decline Codes documentation. 

Step 2 – Process Subsequent Recurring Payments  

Once the initial Cardholder-Initiated Transaction (CIT) has been successfully completed and the recurring agreement has been established, SIBS Gateway automatically processes all subsequent Merchant-Initiated Transactions (MITs) according to the recurring schedule configured during the initial payment. 

This step consists of the following actions: 

• Action 1 – Automatic Execution of Recurring Payments  
• Action 2 – Get Transaction Status (Recommended)  

Action 1 – Automatic Execution of Recurring Payments 

No further payment requests are required from the merchant. 

Using the recurring configuration defined during the initial CIT, SIBS Gateway automatically executes each recurring Merchant-Initiated Transaction (MIT) according to the configured: 

• Initial date (schedule.initialDate)  
• Final date (schedule.finalDate)  
• Billing interval (schedule.interval)  
• Amount configuration (amountQualifier)  

The merchant does not need to submit additional API requests for each recurring payment, as SIBS Gateway manages the recurring execution automatically throughout the lifetime of the recurring agreement. 

Action 2 – Get Transaction Status (Optional but Recommended) 

After a recurring payment has been processed, you can verify its processing status using the Status API. 

Using the Status API is strongly recommended, as it allows your system to retrieve the latest processing status and confirm the final outcome of each recurring payment. 

Unlike the Card Purchase request performed during the initial CIT, the Status API uses the Bearer Token in the Authorization header. 

Example Request 

Step 3 – Receive Recurring Payment Notifications (Optional) 

To further automate your integration, you can configure Webhooks to receive asynchronous notifications whenever a recurring payment is processed. 

When Webhooks are enabled, SIBS Gateway automatically sends event notifications to the merchant’s configured endpoint after each recurring Merchant-Initiated Transaction (MIT), allowing your system to react to payment events in real time. 

Typical notifications include: 

• Recurring payment successfully processed  
• Recurring payment declined  
• Recurring payment pending  
• Recurring payment processing completed  

Webhooks complement the recurring payment integration by providing an event-driven mechanism for receiving transaction updates, making it easier to keep your subscription or billing systems synchronized with the latest payment status. 

For information about configuring Webhooks, supported events and implementation details, refer to the Webhooks Integration documentation. 

Learn more about Webhooks here.