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 the Status Inquiry endpoint

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 the Status API

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)

Step 1 – Create Checkout

The merchant initiates the payment by creating a checkout.

Endpoint

POST <ROOT_URL>/api/v2/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="https://spg.qly.site1.sibs.pt/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.

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
• InProcessing
• Success

Recommended behavior:

• Display a “processing payment” state
• Trigger backend status validation

The backend must use the transactionID obtained during checkout to perform a Status Inquiry request.

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

 

They must not be used to determine the final transaction outcome.

Step 5 – Confirm Final State (Status Inquiry)

The merchant must validate the final transaction state.

Endpoint

GET <ROOT_URL>/api/v2/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"
    }
}

Authoritative Rule

The Status endpoint is the single source of truth for the final transaction state.

This ensures consistency between:

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

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

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 is mandatory before final decision
• 3DS flows may introduce intermediate states
• transactionID must be used across all steps

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 for final validation

This approach guarantees consistency, reliability, and correctness across all transaction scenarios.