[THK] D.2.2.2 Recurring Payments – Credit Card Authorization [Server-to-Server Integration]

Purpose

This flow enables the merchant to perform the initial Cardholder Initiated Transaction (CIT) for a recurring payment agreement using the Merchant environment to securely collect the Customer’s credit card data.

In this process:

The customer provides card details through the Merchant environment
The transaction is processed as an Authorization (AUTH)
The recurring agreement is established through Merchant Initiated Transaction (MIT) parameters

After this initial step:

No further customer interaction is required for recurring payments
The merchant must use the MIT API (server-to-server) to perform subsequent recurring charges

Prerequisites (once per merchant/environment)

You need the following credentials and configuration elements before calling the SIBS SPG APIs:

AuthToken : used as Authorization: Bearer <AuthToken> for REST calls
TerminalId : the terminal ID assigned to the merchant, by the SIBS OnBoarding team
X-IBM-Client-Id : merchant application identifier assigned by the SIBS OnBoarding team

Choose environment root URLs (you will use them in the API base URL and in the widget URL).

Please refer to the API Requests documentation page for more information.

IMPORTANT – PCI DSS REQUIREMENT

In Credit Card Server-to-Server integrations, the merchant collects, processes and transmits cardholder data (PAN, CVV, expiry date).

This means:

- The merchant environment must be PCI DSS compliant
- Card data must never be stored unless tokenized
- Sensitive card data must never be logged
- Card data must never be stored unless explicitly allowed under PCI scope
- Secure transmission (HTTPS/TLS 1.2+) is mandatory

SIBS strongly recommends using tokenization for recurring payments.

Tokenization replaces card data with a secure identifier that can be used for future payments without storing the card number.

If PCI scope reduction is required, use the Form Integration instead.

In Server-to-Server integrations, the merchant must ensure:

Sensitive card data is never logged (application logs, monitoring tools, APM)
Memory handling avoids unnecessary exposure of PAN and CVV
Secure key management and access controls are enforced
All communication channels use strong TLS configurations

Failure to enforce these controls may result in compliance violations and security risks.

Overview

Recurring card payments are based on an initial Cardholder Initiated Transaction (CIT) followed by one or more Merchant Initiated Transactions (MIT).

The CIT (Customer Initiated Transaction) can be performed with a zero or non-zero amount, depending on whether the first payment is collected during authorization or deferred to a later MIT.

The CIT establishes the customer consent and recurring agreement. After a successful CIT, future recurring collections can be executed without customer interaction.

It is used to:

Authenticate the cardholder (Strong Customer Authentication when applicable)
Collect explicit consent for future recurring payments
Register a stored credential for subsequent Merchant Initiated Transactions (MIT)

This step is mandatory before any Merchant Initiated Transaction (MIT) can be executed.

A MIT is not a customer-present authorization and does not perform Strong Customer Authentication (SCA). It relies on the original CIT authorization and stored credentials.

Stored Credential Model

This flow establishes the stored credential required for recurring payments.

The first transaction is a Cardholder Initiated Transaction (CIT)
Future recurring payments are executed as Merchant Initiated Transactions (MIT)
The merchant must store:
- transactionId and/or token (if tokenization is enabled)
- Authorization reference data (required for MIT)

These identifiers are required to perform future recurring charges.

IMPORTANT – Recurring Payment Model

This flow implements the Cardholder Initiated Transaction (CIT) required for recurring payments.

During this step:

The customer provides card details through the Merchant environment
The cardholder is authenticated (3DS when applicable)
A Stored Credential agreement is established
A token will be generated for future use

This authorization enables subsequent Merchant Initiated Transactions (MIT), which are executed without customer interaction.

Transaction Lifecycle Separation

The recurring card flow is composed of three distinct operations:

AUTH (CIT) → customer-present authorization via Merchant environment
CAPTURE → optional settlement of the initial authorization
MIT → subsequent recurring payments without customer interaction

These operations are independent and must not be confused.

API Request Flow

This flow performs the initial Cardholder Initiated Transaction (CIT) required for recurring payments.

It is used to:

Authenticate the cardholder (3DS / SCA when applicable)
Collect consent for future charges
Register a stored credential for Merchant Initiated Transactions (MIT)

In this flow, the process is divided into:

Prepare the checkout (server-to-server)
Collect the Customer’s credit card details in the Merchant environment (PCI DSS compliant)
Perform card Authorization (CIT) using the collected cardholder data
Validate authorization response and confirm status
Check authorization status (back-end)

Recurring Payment Model

Authorization (this step) → Cardholder Initiated Transaction (CIT)
Future recurring payments → Merchant Initiated Transactions (MIT)

A successful CIT is required before any MIT can be performed.

IMPORTANT – Server-to-Server Flow Characteristics

In Server-to-Server integration:

The merchant collects and transmits cardholder data
The authorization is triggered directly via API
No hosted payment form or browser redirection is involved

The merchant is fully responsible for:

PCI DSS compliance
Secure handling of cardholder data
Proper implementation of authentication flows (e.g., 3DS when applicable)

1) PREPARE THE CHECKOUT (SERVER-TO-SERVER)

1.1 POST Checkout Payment to:

curl -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/payments" \
  --header "Authorization: Bearer <AuthToken>" \
  --header "X-IBM-Client-Id: <ClientId>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "merchant": {
        "terminalId": "<terminalId>",
        "channel": "web",
        "merchantTransactionId": "unique-order-id"
    },
    "transaction": {
        "transactionTimestamp": "<currentDate>",
        "description": "Transaction short description",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 5.10,
            "currency": "EUR"
        },
        "paymentMethod": [
            "CARD"
        ]
    },
    "customer": {
      "customerInfo": {
        "customerName": "Onboarding",
        "customerEmail": "Onboarding@teste.com",
        "shippingAddress": {
          "street1": "Rua 123",
          "street2": "Porta 456",
          "city": "Lisboa",
          "postcode": "1200-999",
          "country": "PT"
        },
        "billingAddress": {
          "street1": "First street",
          "street2": "Menef Square",
          "city": "Lisbon",
          "postcode": "1700-123",
          "country": "PT"
        }
      }
    },
    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "amountQualifier": "ESTIMATED"
    }
  }'

Headers

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

Important

Authorization (AUTH) validates the transaction and may reserve funds on the cardholder account (if amount > 0), but it does not transfer funds.

A payment is only completed after a successful Capture operation.

This flow separates:

Authorization (AUTH) → reserves funds
Capture → transfers funds

Authorization Amount Behaviour

If amount = 0 (Zero-Amount Authorization / Tokenization)
- No funds are reserved and no financial movement occurs
- Used for card verification and stored credential (token) creation
- This is the standard approach for recurring payment setup (CIT)

IMPORTANT: A Capture operation cannot be performed directly. To execute a payment, the merchant must:

Perform a Merchant Initiated Transaction (MIT)
Then perform a Capture operation

If amount > 0
- Funds are reserved on the cardholder account
- The transaction can be completed via a Capture operation
- This can be used to authorize the first customer-present transaction (CIT). The payment is completed only after a subsequent Capture operation.

NOTE: Capture can be full or partial, depending on the business use case

What you do in this step

Create a new payment session
Set paymentType = AUTH
Restrict payment method to "CARD"
Define the authorization amount:
0 → card verification only and credential registration
> 0 → authorization with funds reservation
Provide customer information (required for fraud checks and 3DS)

1.2. Store from the successful response:

From the Checkout response, you must store:

transactionID : used in the next step to submit credit card details to SIBS SPG
transactionSignature : used in the next step to submit credit card details to SIBS SPG
paymentMethodList : (SIBS SPG may also return available methods)

Also, the following values will have an important role after the authorization step, namely:

transactionID : used to capture the final amount and execute subsequent MIT transactions
transactionTimestamp (from the checkout request) : used to capture the final amount and execute subsequent MIT transactions
merchantTransactionId : internal reconciliation id
Authorization amount : authorized amount by the Client

Notes

merchantTransactionId is your internal order identifier (maximum 35 characters, unique per transaction).
paymentType must be "AUTH" for two-step purchase
The customer.customerInfo block is required for Credit Card transactions according to the merchant configuration defined during onboarding.
The checkout session expires after 10 minutes. After expiration, the hosted form cannot be rendered and a new Checkout must be created.
Tokenization can be requested by adding the tokenisation block to the payload (see Tokenization section).

2) PERFORM CARD AUTHORIZATION (SERVER-TO-SERVER)

Goal: Submit cardholder data directly to SIBS Payment Gateway to authorize the transaction amount.

This step performs the Authorization only. Funds are reserved but not captured.

IMPORTANT – PCI DSS REQUIREMENT

In a Server-to-Server Credit Card integration:

The merchant environment receives and transmits cardholder data
Card data flows through the merchant’s systems
The merchant is fully within PCI DSS scope

The merchant is responsible for:

Secure handling of PAN, CVV, expiry date, and cardholder name
Secure transmission (TLS 1.2 or higher)
Preventing storage of sensitive authentication data
Ensuring compliant infrastructure and processes

At this stage, the merchant backend is transmitting sensitive cardholder data:

PAN
Secure Code (CVV/CVC)
Validation Date
Cardholder Name

The collection, processing and transmission of these fields must be fully PCI DSS compliant.

The merchant must ensure:

Card data is never logged
Card data is never stored (unless explicitly allowed under PCI scope)
TLS encryption is enforced
Monitoring systems do not capture raw payloads

If PCI compliance cannot be ensured, use Form Integration instead.

2.1 Collect Card Data (PCI DSS Compliant)

The merchant backend must securely collect the cardholder data required for authorization:

PAN : The full card number printed on the card (Primary Account Number).
secureCode : The card security code (CVV/CVC), used for additional fraud validation.
validationDate : The card expiry date, sent in ISO 8601 format.
cardholderName : The name of the cardholder as printed on the card.

All these fields are considered sensitive cardholder data and must be handled in full compliance with PCI DSS requirements.

If 3DS challenge flow is required, the transaction may remain in Pending until authentication is completed.

2.2 Initiate Card operation (AUTH)

curl --location 'https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/card/purchase' \
--header "X-IBM-Client-Id: b824198a-321c-4f53-9bcb-832281d95735" \
--header "Authorization: Digest {transactionSignature}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
  "cardInfo": {
    "PAN": "5309770069960461",
    "secureCode": "220",
    "validationDate": "2025-12-10T00:00:00.000Z",
    "cardholderName": "SIBS",
    "createToken": true
  },
  "actionProcessed": {
    "id": "123456789",
    "type": "THREEDS_METHOD",
    "executed": true
  }
}'

Headers

Authorization: Digest {transactionSignature}
X-IBM-Client-Id: {clientId}
Content-Type: application/json
Accept: application/json

Field Notes

cardInfo

PAN : Full card number
secureCode : CVV/CVC (numeric string, typically 3 or 4 digits)
validationDate : Expiry date in ISO 8601 format
cardholderName : Name printed on the card
createToken :
- true : SPG generates a reusable card token
- false : No token is created

actionProcessed

Used when 3DS Method has already been executed on the merchant side.

type : Must be THREEDS_METHOD
executed : Must be true if already executed
id : Identifier of the processed action

If no prior 3DS Method step was performed, this object may be omitted depending on your integration model.

2.3 Immediate Response Behaviour (AUTH)

For paymentType = AUTH:

Authorization and Capture are performed in separate steps.
A separate Capture call is required to settle the authorized amount.

Possible high-level statuses:

Success : Authorization successfully processed (for paymentType = AUTH)
Declined : Authorization rejected
Pending / InProcessing : Additional authentication or processing in progress (e.g., 3DS challenge)
Timeout
Error

The merchant should always confirm the final state via the Status endpoint (Step 3), especially in case of Pending or InProcessing.

3) CHECK AUTHORIZATION STATUS UNTIL IT IS FINALIZED (BACK-END)

Goal: Confirm the final authorization status after the authorization process is completed.

Even though Credit Card is a near real-time payment method, the final result must always be validated server-to-server.

3.1 When to check status

You must verify the transaction status:

After receiving the authorization response
After receiving a Merchant Notification (if configured)

Unlike Multibanco Reference, Credit Card payments do not remain pending for extended periods.

However:

During 3D Secure authentication, the transaction may temporarily remain in Pending while the authentication result is being processed by SPG.

The authorization must only be considered finalized after confirming the status via API.

3.2 Status endpoints you can use

SIBS SPG documents two common options:

GET /api/v2/payments/{transactionID}/status (where {transactionID} is transactionID from the checkout operation)
GET /api/v2/payments/status?merchantTransactionId=... (query by your merchant transaction id)

curl -v -X GET "https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/status" \
--header "X-IBM-Client-Id: <ClientId>" \
--header "Authorization: Bearer <AuthToken>" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

Where {transactionID} is the value obtained in the Checkout response (Step 1).

3.3 Required headers (status call)

Authorization: Bearer <AuthToken>
X-IBM-Client-Id: <clientid>
Content-Type: application/json
Accept: application/json

3.4 What statuses to expect (high level)

The response includes paymentStatus, typically with values such as:

Success
Declined
Error
Pending
InProcessing
Timeout

Typical status interpretation

Success: the authorization was successfully processed.
Declined: the authorization was rejected.
Error: a technical or processing error occurred during authorization.
Pending: the transaction is still being processed.
InProcessing: the transaction is in processing.
Timeout: the operation timed out before a final result was obtained.

The recurring authorization flow should only be considered successful when:

paymentStatus = "Success“
returnStatus.statusCode = "000“

Note: This does not imply that funds were captured. A separate Capture operation is required to complete the payment.

Only then should the authorization be considered successfully completed.

Error Handling

If the authorization fails:

paymentStatus will indicate failure
No token will be generated
The transaction must not be retried automatically without customer interaction

Merchants should:

Display a clear error message to the customer
Allow retry through a new checkout session

Failed authorizations must not be retried automatically without customer interaction. A new checkout session must be created for each retry attempt.

Transaction Token

The token generated for this operation is returned in this request in the token field.

Secure Token Storage

If tokenization is enabled, the authorization response will include a card token.

The merchant must store this token securely, as it is required for all subsequent Merchant Initiated Transactions (MIT).

The token replaces card details and must:
be stored server-side only
never be exposed in frontend applications
be protected according to security best practices

If the token is not stored at the time of the response, it cannot be retrieved later.

In this case, recurring payments cannot be executed and a new customer interaction (new checkout) will be required.

Token Dependency for Recurring Payments

The token generated in the initial transaction is mandatory for all subsequent Merchant Initiated Transactions (MIT).

If the token is not stored, recurring payments cannot be performed without requiring a new customer interaction.

3.5 Polling strategy (minimal, practical skeleton)

Poll GET /api/v2/payments/{transactionID}/status every few seconds
Stop when paymentStatus is final (Success, Declined, Error)
If still Pending or InProcessing continue polling with a timeout safeguard

If the status is:

Pending
InProcessing

The merchant should:

Wait a few seconds
Poll the Status endpoint again
Stop polling when a final state is reached

Recommended polling strategy:

Interval: 3–5 seconds
Maximum duration: 60–120 seconds
Always implement idempotent processing logic

Even if polling is implemented, SIBS SPG supports Merchant Notification (webhooks) for asynchronous payments.

3.6 Recommended validation strategy

For Credit Card Server-to-Server Integration:

If Pending, retry status after a short delay (few seconds).
Stop when a final state is reached (Success, Declined, Error).

Polling for Credit Card should be short-lived and limited to the authentication window.

Important Notes

Credit Card is a near real-time payment method, except when Strong Customer Authentication (3D Secure) introduces an authentication step.
There is no extended waiting period (unlike Multibanco Reference).
The final payment confirmation must always be validated server-to-server.

4) CAPTURE THE AUTHORIZED TRANSACTION (SERVER-TO-SERVER) (OPTIONAL)

Goal: When the authorization (CIT) is performed with an amount greater than zero, funds may be reserved on the card.
In this case, the merchant may decide to capture the authorized amount immediately after a successful authorization.

This step is applicable when:

The authorization request was performed with an amount > 0
And the authorization result is returnStatus.statusCode = “000” and paymentStatus = “Success”

The capture operation is optional in the context of subsequent payments
If no capture is performed:
- The authorization may expire after a certain period (issuer dependent)
If capture is performed:
- The authorized amount is debited from the cardholder
- This corresponds to the settlement of the initial authorized transaction

This operation must not be confused with subsequent recurring payments, which are executed as Merchant Initiated Transactions (MIT).

In a recurring payment authorization flow, authorization does not transfer funds.
Funds are only settled after this capture call.

What you do

4.1 POST Capture request

curl -v -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/capture" \
--header "X-IBM-Client-Id: <ClientId>" \
--header "Authorization: Bearer <AuthToken>" \
--header "Accept: application/json" \
--header "Content-Type: application/json"
--data '{
    "merchant": {
        "terminalId": "<terminalId>",
        "channel": "web",
        "merchantTransactionId": "unique-capture-id"
    },
    "transaction": {
        "transactionTimestamp": "2026-02-27T18:03:05.190Z",
        "description": "Capture operation",
        "amount": {
            "value": 5.00,
            "currency": "EUR"
        }
    }
}'

Where:

{transactionID} is the transaction created in the checkout step and authorized by the customer.

The capture must only be considered successful when:

paymentStatus = "Success“
returnStatus.statusCode = "000“

What happens

SPG validates that the transaction is in a capturable state (Authorized).
If valid, SPG captures the amount (full or partial if supported/configured).
The transaction moves toward a final state where funds are settled.

What to store from the response

Store at least:

Capture result status (success/failure)
The transactionID returned in the capture response (it is different from the original authorization transactionID).
Your merchantTransactionId for reconciliation/audit
Captured amount

Important Notes

The capture amount must not exceed the authorized amount.
Partial capture depends on merchant configuration / scheme rules.
Capture operations must be implemented idempotently to prevent duplicate settlement in case of retry scenarios or network failures.
If the authorization expires before capture, the reserved funds are released and the capture operation will fail.
If the capture operation fails, the authorization remains open until it expires. In this case, funds are not transferred and a new transaction may be required depending on the business scenario.

5) CHECK CAPTURE STATUS (BACK-END)

Goal: Confirm the final capture outcome after the capture operation.

5.1 When to check status

You must verify the capture transaction status right after the capture operation returns successfully. The transaction must only be considered finalized after confirming the status via API.

5.2 Status endpoints you can use

SIBS SPG documents two common options:

GET /api/v2/payments/{transactionID}/status (where {transactionID} is the transactionID returned by the Capture operation)

curl -v -X GET "https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/status" \
--header "X-IBM-Client-Id: <ClientId>" \
--header "Authorization: Bearer <AuthToken>" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

Where {transactionID} is the value returned by the Capture operation.

5.3 Required headers (status call)

Authorization: Bearer <AuthToken>
X-IBM-Client-Id: <clientid>
Content-Type: application/json
Accept: application/json

5.4 What statuses to expect (high level)

The response includes paymentStatus, typically with values such as:

Success
Declined
Error
Pending
InProcessing
Timeout

Typical Status interpretation

Success: the capture operation was successfully processed and funds have been transferred.
Declined: the transaction was rejected.
Error: a technical or processing error occurred during capture.
Pending: the transaction is still being processed.
InProcessing: the transaction is in processing.
Timeout: the operation timed out before a final result was obtained.

Final success criteria

The transaction should only be considered successful when:

paymentStatus = "Success“
returnStatus.statusCode = "000“

Only then should the transaction be considered successfully completed, with funds transferred.

Next Step – Recurring Collection

After a successful Authorization (CIT), recurring payments can be executed without customer interaction.

In order to perform future recurring payments, you have to:

Store the transactionID returned by the successful CIT flow (returned by the checkout operation)
Store the transactionTimestamp used to perform the checkout for the CIT request
Store the token returned by the successful CIT flow (returned by the status check operation)
Store the recurring agreement context associated with that transaction

Each Merchant Initiated Transaction (MIT) must reference the original CIT transaction using:

originalTransaction.id → the transactionID from the successful CIT
originalTransaction.datetime → the transactionTimestamp from the CIT request

These values are mandatory to execute recurring payments.

Refer to:

Recurring Payments – Credit Card Collection

for details on how to perform Merchant Initiated Transactions (MIT) and capture recurring payments.

Key Characteristics

Customer interaction required only once (authorization step)
Card data handled by the merchant (full PCI DSS scope applies)
Tokenization enables future payments
No customer interaction required for recurring charges
Supports subscription and recurring billing models
Initial AUTH, CAPTURE and MIT are separate operations and must be implemented independently

PCI DSS Responsibilities – Summary

Server-to-Server Credit Card integration:

Does not reduce PCI scope
Requires full PCI DSS compliance
Involves direct handling of cardholder data
Places full responsibility on the merchant

The merchant must ensure:

Secure network architecture
No storage of sensitive authentication data
Secure logging policies
Proper access controls
Regular vulnerability assessments

Failure to comply may result in:

Card scheme penalties
Fines
Loss of acquiring privileges
Contract termination

PAYMENT GATEWAY

[THK] D.2.2.2 Recurring Payments – Credit Card Authorization [Server-to-Server Integration]

Purpose

Prerequisites (once per merchant/environment)

Overview

Stored Credential Model

IMPORTANT – Recurring Payment Model

API Request Flow

IMPORTANT – Server-to-Server Flow Characteristics

1) PREPARE THE CHECKOUT (SERVER-TO-SERVER)

Important

Authorization Amount Behaviour

2) PERFORM CARD AUTHORIZATION (SERVER-TO-SERVER)

3) CHECK AUTHORIZATION STATUS UNTIL IT IS FINALIZED (BACK-END)

Typical status interpretation

Secure Token Storage

4) CAPTURE THE AUTHORIZED TRANSACTION (SERVER-TO-SERVER) (OPTIONAL)

5) CHECK CAPTURE STATUS (BACK-END)

Typical Status interpretation

Final success criteria

Next Step – Recurring Collection

Key Characteristics

On this page: