Overview

This example illustrates a complete end-to-end flow for a one-off payment using Credit Card via Form Integration.

It demonstrates how the merchant system:

• Creates a checkout session
• Redirects the customer to the hosted payment form
• Handles customer redirection after payment execution
• Processes asynchronous updates via Webhooks
• Confirms the final transaction state using a final webhook paymentStatus or Status Inquiry when required

This scenario represents a hybrid synchronous/asynchronous flow, where final transaction confirmation requires coordination between frontend interaction, webhook processing, and backend validation.

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

Process a one-off payment using a credit card through the hosted SPG form, ensuring:

• Secure customer interaction
• Correct handling of redirection and authentication (e.g., 3DS)
• Reliable transaction state tracking
• Final reconciliation 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 – One-Off Credit Card Form Integration Flow

Step 1 – Create Checkout

The merchant initiates the payment by creating a checkout.

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-CC-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-15T10:00:00.000Z",
        "description": "Order payment",
        "moto": false,
        "paymentType": "PURS",
        "amount": {
            "value": 49.90,
            "currency": "EUR"
        },
        "paymentMethod": [
            "CARD"
        ]
    },
    "customer": {
        "customerInfo": {
            "customerName": "John Doe",
            "customerEmail": "john.doe@email.com",
            "billingAddress": {
                "street1": "Street 1",
                "city": "Lisbon",
                "postcode": "1000-000",
                "country": "PT"
            }
        }
    }
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Card → Checkout Card

Key Outputs

• transactionID → primary correlation identifier
• formContext → required to render 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 – Redirect Customer to Hosted Payment Form

Using the formContext, the merchant renders 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 inputs card details
• 3DS authentication may be triggered
• SPG processes the transaction

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 payment execution, the customer is redirected to the configured redirectUrl.

Important

 

The redirect does not represent the final transaction state.

 

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 payment” state
• Trigger backend status validation

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

Step 4 – Receive and Process Webhook Notifications

SPG sends webhook notifications when the transaction state changes.

Example Payload

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2ExampleTx123456789",
    "paymentType": "PURS",
    "notificationID": "notif-123456"
}

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-123456"
}

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 Final State (Status Inquiry APIs)

The merchant may validate the final transaction state using Status Inquiry when no final 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",
    "transactionID": "s2ExampleTx123456789",
    "amount": {
        "value": 49.90,
        "currency": "EUR"
    }
}

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.

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

Expected Final Outcome

The merchant system must finalize the transaction based on paymentStatus:

• Success → Payment completed
• Declined → Payment failed
• Other states → Continue monitoring

Implementation Notes

• Redirect must never finalize the transaction
• Webhooks must be processed asynchronously
• Status validation should be used when no final webhook is available or when additional confirmation, recovery, or reconciliation is required
• 3DS flows may introduce intermediate states
• transactionID must be used across all steps

Operational logs and monitoring systems should correlate transactionID, merchantTransactionId, and notificationID across all processing 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

• Advanced scenarios (testing)

SPG Sandbox → CARD → Card - Success / Declined

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

Recommended Usage

• Execute Step 1 to generate transactionID
• Perform payment via hosted form
• Use Status requests to validate final outcome
• Use Sandbox scenarios to simulate different results

Final Notes

This example demonstrates a complete real-world integration pattern combining:

• Hosted payment execution
• Asynchronous event handling
• Backend reconciliation

For production-grade implementations:

• Use API responses for immediate flow 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 approach guarantees consistency, reliability, and correctness across all transaction scenarios.