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 logged
• Card data must never be stored unless explicitly allowed under PCI scope
• Secure transmission (HTTPS/TLS 1.2+) is mandatory

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

API Request Flow

In a Two-step Credit Card (AUTH → CAPTURE) Server-to-Server Integration, the process is divided into:

1. Checkout creation (server-to-server – AUTH configuration)
2. Card Authorization (server-to-server – card data submitted via API)
3. Authorization status validation (backend)
4. Capture the authorized transaction (server-to-server)
5. Capture status validation (backend)

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

Goal: Create a checkout session configured for Authorization only (paymentType = AUTH) and obtain the identifiers required for the subsequent server-to-server operations (authorization, status validation and capture).

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": "2026-02-27T17:57:06.498Z",
        "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"
        }
      }
    }
  }'

Important

• paymentType must be set to “AUTH“
• paymentMethod must include "CARD" (i.e., ["CARD"])
• merchantTransactionId must be unique per transaction

Headers

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

What you do in this step

• Create a new payment session.
• Define the payment type (AUTH for the first step for the two-step payment).
• Restrict the payment method to "CARD".
• Provide customer information as required by the merchant configuration defined during onboarding.
• Send the total amount and currency.

1.2. Store from the successful response:

From the Checkout response, you must store:

• transactionID : used in subsequent calls
• transactionSignature: required to authorize the card authorization call

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

• transactionID : used to capture the final amount
• merchantTransactionId : internal reconciliation id
• Authorization amount : amount reserved by the issuer (from the AUTH step)

Field Notes

merchant

• terminalId : Merchant terminal provided by SIBS
• channel : Integration channel (web, app, etc.)
• merchantTransactionId : Unique merchant-side identifier (use idempotency controls to prevent duplicates)

transaction

• transactionTimestamp : Current timestamp in ISO 8601 format
• description : Free text description
• moto : Mail Order / Telephone Order flag
• paymentType : AUTH (Authorization only for two-step flow)
• amount.value : Decimal value (dot as decimal separator, e.g. 19.20)
• amount.currency : ISO currency code
• paymentMethod : Must include "CARD"

customer

Billing information is required for card transactions and may be used for fraud screening and 3DS evaluation.

Notes

• merchantTransactionId is your internal order identifier (maximum 35 characters, unique per transaction).
• paymentType must be set to "AUTH" for the first step of the two-step flow
• 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, card operations cannot be performed, 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 SPG 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
• secureCode (CVV/CVC)
• validationDate
• cardholderName

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 : Payment authorized (for paymentType = AUTH)
• Declined : Payment 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 PAYMENT STATUS UNTIL IT IS AUTHORIZED (BACK-END)

Goal: Confirm the final payment outcome after the card authorization (and 3DS authentication, if applicable).

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 should:

• Listen to Merchant Notifications (recommended)
• Optionally poll the transaction status

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 with values such as:

• Success : Payment authorized (funds reserved)
• Declined : Payment rejected
• Pending : Awaiting additional processing (e.g. 3DS)
• InProcessing : Transaction still being processed
• Timeout : Approval timeout
• Error : Approval or processing error

The merchant should consider the Authorization final only when a definitive status (e.g., Success, Declined, Error) is obtained.

Credit Card Behavior

• Success : Authorization approved (funds reserved)
• Declined : Transaction refused by issuer
• Error : Technical or processing error
• Pending : Temporary state during authentication or processing (e.g., 3D Secure challenge flow)

The authorization must only be considered successful when:

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

Only then should the transaction be considered Authorized. Funds are now reserved but not captured.

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:

1. Wait a few seconds
2. Poll the Status endpoint again
3. 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.

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

Goal: Convert a previously authorized transaction (funds reserved) into a settled payment by executing a Capture operation.

In a Two-step flow, authorization does not transfer funds.
Funds are only settled after this capture call.

What you do

4.1 Decide when to capture

Capture is triggered after your business condition is met, for example:

• Order validated / stock confirmed
• Service delivered or ready to deliver
• Shipment confirmed
• Manual approval completed

Important: Capture must occur within the authorization validity window (scheme rules / issuer policies).

4.2 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 original authorized transaction identifier (from the Checkout/AUTH flow) to be captured.

The capture must only be considered successful when (capture transaction):

• 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.

5) CHECK PAYMENT (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 value 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 (Step 4).

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

Credit Card Behaviour

• Success : Capture approved and funds settled.
• Declined : Transaction refused by issuer
• Error : Technical or processing error
• Pending : Temporary state while the capture is being processed by SPG.

The capture must only be considered successful when:

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

Only then should the transaction be considered Captured and Settled.

⚠ PCI DSS Responsibilities – Summary

Two-step 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