[THK] D.2.2.1 Recurring Payments – Credit Card Authorization [Form Integration]

Purpose

This flow enables the merchant to perform the initial Cardholder Initiated Transaction (CIT) for a recurring payment agreement using the SIBS SPG hosted payment form.

In this process:

The customer enters card details in the SPG Form
The transaction is processed as an Authorization (AUTH)
The recurring agreement is established through Merchant Initiated Transaction (MIT) parameters

After this initial step:

The SPG Form is not used again 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.

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.

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 – PCI DSS SCOPE REDUCTION

In Form Integration:

Cardholder data is collected directly by the SIBS hosted payment form
The merchant does not handle sensitive card data (PAN, CVV)
PCI DSS scope is reduced

This means:

The merchant does not handle card data
The merchant is not exposed to full PCI DSS scope
Sensitive card data (PAN, CVV) never transits through the merchant system

This integration method is recommended when:

PCI DSS scope reduction is required
The merchant does not want to handle card data directly

IMPORTANT – Recurring Payment Model

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

During this step:

The customer enters card details in the SIBS hosted form
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 SPG Form
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)
Redirect the customer to the SPG Form
Cardholder performs card Authorization (CIT)
Handle return and validate authorization
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.

1) Prepare the checkout (server-to-server)

Goal: Create a checkout session and configure the transaction for card authorization (CIT).

This is a Cardholder Initiated Transaction (CIT)
paymentType must be AUTH
paymentMethod must include “CARD“
This transaction establishes the stored credential for future MIT usage

What you do

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 : (you’ll inject it in the widget script URL)
transactionSignature : (you’ll inject it into the HTML form attribute)
formContext : (you’ll inject it into the HTML form attribute)
paymentMethodList : (SIBS SPG may also return available methods)

These values are required to:

Load the SIBS SPG widget
Render the payment form
Perform server-side status validation

Also, the following values will have an important role after the authorization in the form, 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) Create the payment form link (Widget) + customization (front-end)

Goal: Render the SPG hosted credit card form and allow the customer to perform the Authorization.

In Form Integration:

Card data (PAN, CVV) is collected directly by the SIBS Payment Form
The merchant does not handle sensitive card data
PCI scope is reduced

2.1 Include the SIBS SPG widget script (using transactionID)

Add the script tag to your checkout page:

<script src="https://spg.qly.site1.sibs.pt/assets/js/widget.js?id={transactionID}"></script>

This is the standard Form Integration approach. The script URL must include the transactionID returned in the Checkout response.

2.2 Add the <form> element and inject formContext + transactionSignature + config/style

You must have a form with class paymentSPG and the required SPG attributes:

<form class="paymentSPG"
      spg-context="{formContext}"
      spg-signature="{transactionSignature}"
      spg-config="{formConfig}"
      spg-style="{formStyle}">
</form>

SIBS SPG explicitly defines:

spg-context : the formContext you received from Checkout
spg-signature : the transactionSignature you received from Checkout
spg-config : merchant configuration (JSON string),
spg-style : optional styling configuration (JSON string).

2.3 formConfig – minimal config for Credit Card two-step purchase

At minimum, your config must:

Restrict the form to Credit Card using paymentMethodList
Set redirectUrl (where the customer returns after the form finishes)
The amount is defined in the Checkout request and does not need to be redefined in formConfig.
Set language to match your checkout language.

Example (conceptual):

const formConfig = JSON.stringify({
  paymentMethodList: ["CARD"],
  redirectUrl: "https://merchant.example.com/payment-return",
  language: "en"
});

Supported values for paymentMethodList include MBWAY, REFERENCE, CARD (display depends on merchant permissions).

2.4 formStyle – optional UI customization

If you want to align the SIBS SPG form with your brand, SIBS SPG supports a style object with parameters like layout/theme/colors/font.
Example (conceptual):

const formStyle = JSON.stringify({
  layout: "default",
  theme: "light",
  color: { 
      primary: "#0033A1" 
  }
});

Optional: react to “Pay” click events in real time

SIBS SPG supports event monitoring via window.postMessage from the iframe so you can show a spinner / tracking / UX actions when the user clicks “Pay”.

What Happens After Form Submission?

The customer enters card details in the hosted form.
The transaction is sent to the acquiring network.
Strong Customer Authentication (3D Secure) may be automatically triggered by the issuer.
The issuing bank approves or declines the transaction.
The customer is redirected to the configured redirectUrl.
The final authorization status must be confirmed server-to-server (Step 3).

Asynchronous Processing

When 3D Secure authentication is triggered, the authorization may not be completed immediately.

The transaction may remain temporarily in Pending status.

The final result must always be confirmed via backend status validation.

Credit Card Behaviour

Credit Card is a near real-time payment method.
Authorization response is typically immediate in non-3DS scenarios.
3D Secure authentication may introduce a short processing period.
The transaction may temporarily remain in Pending only while the 3D Secure authentication result is being processed by SPG.
The authorization must only be considered completed when paymentStatus = "Success“.

IMPORTANT – Backend Validation Required

The redirect (return URL) must not be used as a source of truth.

After the customer is redirected, the merchant must validate the transaction status using a server-to-server request:

GET /api/v2/payments/{transactionID}

Only the backend response must be considered authoritative.

Notes

The form performs Authorization only (funds reserved).
The hosted form is PCI DSS compliant and securely handled by SIBS SPG.
All cardholder data (PAN, secureCode, validationDate, cardholderName) is collected exclusively inside the SIBS SPG environment.
Card data never touches the merchant server, significantly reducing PCI DSS scope.
If the checkout session expires (10 minutes), the hosted form will no longer load correctly, and a new checkout session must be created.
Even after redirection, the final transaction result must always be validated via the status endpoint.

3) CHECK PAYMENT STATUS UNTIL IT IS AUTHORIZED (BACK-END)

Goal: Confirm the final authorization status after the customer completes the Credit Card authorization flow.

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 the customer is redirected to the redirectUrl
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 and capture flow was processed successfully.
Declined: the transaction was refused.
Error: a technical or processing error occurred.
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“

Only then should the recurring authorization flow 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 Recommended validation strategy

For Credit Card Form Integration:

After redirection, immediately call the /status endpoint.
Do not rely solely on front-end redirection parameters.
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 settlement is completed.

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 funds are released and capture 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 obtained in the capture request.

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 refused.
Error: a technical or processing error occurred.
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 recurring authorization flow should only be considered successful when:

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

Only then should the transaction be considered successfully completed and 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 securely by SIBS (PCI scope reduction)
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

PAYMENT GATEWAY

[THK] D.2.2.1 Recurring Payments – Credit Card Authorization [Form Integration]

Purpose

Prerequisites (once per merchant/environment)

Overview

Stored Credential Model

IMPORTANT – PCI DSS SCOPE REDUCTION

IMPORTANT – Recurring Payment Model

API Request Flow

1) Prepare the checkout (server-to-server)

Important

Authorization Amount Behaviour

2) Create the payment form link (Widget) + customization (front-end)

3) CHECK PAYMENT STATUS UNTIL IT IS AUTHORIZED (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: