Overview

This example illustrates a complete end-to-end flow for a two-step payment using Credit Card, where the transaction is split into:

• Authorization (AUTH) → funds are reserved
• Capture (CAPTURE) → funds are collected

It demonstrates how the merchant system:

• Creates a checkout configured for authorization
• Processes customer interaction through the hosted payment form
• Receives asynchronous updates via Webhooks
• Confirms the authorization result using a final webhook paymentStatus or Status Inquiry when required
• Executes a separate capture operation
• Validates the final captured state

This scenario represents a multi-phase transaction flow, requiring strict control of transaction state transitions and correct orchestration between authorization and capture steps.

The execution of this flow can be validated using the SIBS Postman Collections:

• Download SIBS PAYMENT GATEWAY POSTMAN Collection
• Download SPG Sandbox POSTMAN Collection

Goal

Authorize a payment using a credit card and capture the funds in a separate step, ensuring:

• Correct authorization handling
• Proper separation between authorization and capture
• Reliable state validation before capture
• Final reconciliation after capture using a final webhook paymentStatus or Status Inquiry when required

Preconditions

Before executing this flow, the following must be in place:

• Valid SPG credentials:
  • terminalId
  • X-IBM-Client-Id
  • Bearer token
• Configured Webhook endpoint
• Backend capable of storing:
  • transactionID
  • merchantTransactionId
• Hosted form integration correctly implemented

In Postman, ensure the following variables are configured:

• terminalId
• ClientID
• Bearer
• host

(See collection root variables in SIBS PAYMENT GATEWAY POSTMAN Collection)

Figure – Two-Step AUTH → CAPTURE Operational Flow

Step 1 – Create Checkout

The merchant creates a checkout configured for authorization.

Endpoint

POST <ROOT_URL>/payments

Headers

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

Example Request

{
    "merchant": {
        "terminalId": 11111,
        "channel": "web",
        "merchantTransactionId": "ORDER-AUTH-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-15T11:00:00.000Z",
        "description": "Authorization payment",
        "paymentType": "AUTH",
        "amount": {
            "value": 100.00,
            "currency": "EUR"
        },
        "paymentMethod": [
            "CARD"
        ]
    }
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Card → Checkout Card

Key Outputs

• transactionID → primary identifier
• formContext → required for hosted form

The transactionID returned in this step must be used as the primary identifier across all subsequent steps, including webhook processing and status validation.

Step 2 – Customer Interaction (Authorization)

The customer is redirected to the hosted payment form.

<script src="<ROOT_URL>/assets/js/widget.js?id={transactionID}"></script>

<form
  spg-context="{formContext}"
  spg-config='{"redirectUrl":"https://merchant.example.com/return"}'>
</form>

At this stage:

• The customer enters card details
• 3DS authentication may occur
• SPG processes the authorization request

No direct card data handling occurs on the merchant side. This integration model helps reduce PCI DSS scope by ensuring that sensitive cardholder data is collected and processed directly by the hosted SPG payment form.

Step 3 – Handle Customer Redirection

After authorization, the customer is redirected to the merchant.

Important

 

The redirect does not guarantee that the authorization is finalized.

 

At this point, the transaction may still be:

• Pending
• Success
• Declined
• Timeout

according to the transaction lifecycle and finality rules

Recommended behavior:

• Display a “processing authorization” state
• Trigger backend validation

The backend must use the transactionID obtained during checkout when Status Inquiry API requests are required.

Step 4 – Receive and Process Webhook Notifications (Authorization)

SPG sends a notification with the authorization result.

Example Payload

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2ExampleTxAUTH123",
    "paymentType": "AUTH",
    "notificationID": "notif-auth-001"
}

Processing Requirements

• Receive the notification
• Validate authenticity and integrity according to the configured webhook security model (e.g., decryption and header validation)
• Store and process the notification using notificationID as a unique identifier
• Ensure idempotent processing
• Acknowledge correctly

Response to SPG

{
    "statusCode": "000",
    "statusMsg": "Success",
    "notificationID": "notif-auth-001"
}

The notificationID must match the value received in the webhook payload.

Important

 

Webhooks provide event-driven updates.

 

When a webhook contains a final paymentStatus, it may be used for business processing. Status Inquiry should be used when no final webhook is available or when additional confirmation, recovery, or reconciliation is required.

The reconciliation and validation mechanisms described in E. Notifications and Transaction Status should be followed where applicable.

Step 5 – Confirm Authorization (Status Inquiry APIs)

The merchant may confirm that authorization was successful using Status Inquiry when no final authorization webhook is available or when additional confirmation, recovery, or reconciliation is required.

Endpoint

GET <ROOT_URL>/payments/{transactionID}/status

Headers

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

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Card → getStatus

Example Response

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentType": "AUTH",
    "transactionID": "s2ExampleTxAUTH123",
    "amount": {
        "value": 100.00,
        "currency": "EUR"
    }
}

Capture must only be performed if the authorization is confirmed as successful.

 

This ensures consistency between event execution, webhook notifications, and backend processing, particularly in scenarios involving delays, retries, or asynchronous flows.

For scenarios requiring extended operational or financial information, integrations may additionally use the Inquiry Details endpoint documented in E.2 Status Inquiry / Get Status.

Step 6 – Capture the Payment

The merchant initiates the capture operation for the previously authorized transaction.

Endpoint

POST <ROOT_URL>/payments/{transactionID}/capture

Headers

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

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Card → Capture

Example Request

{
    "amount": {
        "value": 100.00,
        "currency": "EUR"
    }
}

Step 7 – Receive Webhook (Capture)

SPG sends a notification for the capture operation.

Example Payload

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentType": "CAPTURE",
    "transactionID": "s2ExampleTxAUTH123",
    "notificationID": "notif-capture-001"
}

Process this webhook using the same idempotent model.

Step 8 – Confirm Final State (Status Inquiry APIs)

The merchant may confirm that the capture operation has been successfully completed using Status Inquiry when no final capture webhook is available or when additional confirmation, recovery, or reconciliation is required.

Endpoint

GET <ROOT_URL>/payments/{transactionID}/status

Headers

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

Example Response

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentType": "CAPTURE",
    "transactionID": "s2ExampleTxAUTH123"
}

Final State Rule

Final transaction state may be determined from a final webhook paymentStatus or via Status Inquiry when required

This ensures consistency between:

• Customer interaction (frontend)
• Webhook notifications
• Backend reconciliation and processing

This ensures consistency between event execution, webhook notifications, and backend processing, particularly in scenarios involving delays, retries, or asynchronous flows.

Expected Final Outcome

• Authorization → Success
• Capture → Success

Only after capture success should the merchant consider the payment completed.

Business fulfillment processes must not be triggered based solely on authorization success without confirmed capture completion.

Implementation Notes

• Authorization and capture are independent steps
• Capture must never be executed without confirmed authorization
• Webhooks must be processed idempotently
• Status Inquiry should be used when no final webhook is available or when additional confirmation is required
• Partial captures may be supported depending on configuration
• Time limits for capture may apply

Operational logs and monitoring systems should correlate transactionID, merchantTransactionId, and notificationID across authorization, capture, webhook processing, and reconciliation stages.

Use of Postman Collection

The Postman Collections should be used as the execution layer for this example.

Relevant Requests

• Checkout

SIBS PAYMENT GATEWAY → Card → Checkout Card

• Status

SIBS PAYMENT GATEWAY → Card → getStatus

• Capture

SIBS PAYMENT GATEWAY → Card → Capture

Use the previously referenced requests to execute each step, validate responses, and simulate different transaction outcomes in sandbox environments.

Recommended Usage

• Execute authorization flow
• Validate status before capture
• Execute capture
• Validate final status

Final Notes

This example demonstrates a complete two-step payment flow requiring strict control of transaction state.

For production-grade implementations:

• Use API responses for immediate control
• Use Webhooks for event awareness
• Use Status Inquiry APIs when no final webhook is available or when additional confirmation, recovery, or reconciliation is required

This ensures correct handling of multi-phase payments and avoids inconsistent or premature transaction finalization.