Overview

SIBS Payment Gateway (SPG) provides two complementary mechanisms for obtaining transaction information:

• Webhooks – push-based notifications triggered by transaction events
• Status Inquiry – pull-based endpoint for querying the current state of a transaction

These mechanisms serve different purposes and should be used together when additional confirmation, recovery, reconciliation, or inconsistency resolution is required.

Conceptual Model

Webhooks

• Event-driven notifications
• Delivered asynchronously
• Used to inform that a change has occurred

Status Inquiry

• On-demand query mechanism
• Returns the latest transaction state available through the query API
• Depending on the payment method and transaction lifecycle stage, the returned state may still evolve asynchronously until final resolution is reached.

Consistency Principle

Webhooks act as event triggers and may communicate final transaction states. Status Inquiry provides the latest transaction state available through the query API and should be used for reconciliation, recovery from missed or delayed notifications, or additional confirmation when required.

Webhook notifications indicate that something has changed, but they do not guarantee that the received state is:

• Final
• Complete
• Delivered in order

For this reason, the merchant system should use Status Inquiry before applying critical business decisions when the webhook does not provide a final state or when additional confirmation, recovery, reconciliation, or inconsistency resolution is required.

Webhook notifications represent events in the transaction lifecycle and may contain a final paymentStatus that can be used for business processing.

Critical Implementation Rule

The webhook endpoint must respond immediately and must not perform synchronous calls to the SPG API (including the Status Inquiry APIs).

Do NOT:

• Call the Status Inquiry during webhook request handling
• Perform heavy business logic before responding
• Block the HTTP response while processing the event

Reason

• Prevent webhook delivery timeouts
• Avoid unnecessary retries from SPG
• Ensure high availability and scalability of the endpoint

When Status Inquiry is required, it must be performed asynchronously after webhook acknowledgement, using the transactionID as the primary correlation identifier.

Recommended Processing Model

The correct implementation pattern is asynchronous.

Detailed webhook reception and asynchronous processing patterns are described in E.1.4 – Receiving and Processing Webhooks.

Sequence Diagram

Status Inquiry APIs

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

This endpoint returns the latest known state of the transaction and should be used for:

• Additional final state confirmation when required
• Reconciliation
• Recovery from missed or delayed events

When to Use Each Mechanism

Use Webhooks to:

• Trigger internal processing when a transaction lifecycle event occurs
• React to asynchronous payment updates
• Initiate internal workflows

Use Status Inquiry to:

• Confirm the final transaction outcome
• Validate critical business decisions
• Resolve transaction-state inconsistencies
• Perform reconciliation

Typical Scenarios

Asynchronous Payment Flow

Webhooks notify transaction events and may contain the final paymentStatus. Status Inquiry should be used to confirm whether the transaction is successful, pending, or failed when no final webhook is available or when additional confirmation is required.

Duplicate or Out-of-Order Webhooks

Webhooks may arrive multiple times or out of sequence. The Status Inquiry ensures correct interpretation.

Missing Webhooks

If a webhook is not received, the transaction state can still be recovered through the Status Inquiry APIs.

Polling and recovery strategies are further described in E.2.5 – Polling Strategy and Best Practices.

Consistency Risks Without This Model

If the asynchronous model is not respected:

• Webhook timeouts may occur
• SPG retries may increase unnecessarily
• Duplicate processing may be triggered
• System performance and scalability may degrade
• Incorrect transaction states may be applied

Best Practices

• Respond to webhooks immediately with HTTP 200 OK and the expected acknowledgement response body
• Process webhook events asynchronously
• Never chain SPG API calls inside webhook response handling
• Validate transaction state using Status Inquiry when additional confirmation, recovery, reconciliation, or inconsistency resolution is required
• Implement idempotent processing
• Log both webhook and status interactions

Summary

Webhooks and the Status Inquiry are complementary:

• Webhooks provide event notification
• Status Inquiry provides the latest transaction state available through the query API

A correct implementation requires:

• Immediate webhook acknowledgement using HTTP 200 OK with valid acknowledgement response body
• Asynchronous processing
• Status validation before applying business logic when required

This model ensures scalable, resilient, and consistent transaction processing across all SPG integrations.

Additional consistency and reconciliation guidance is provided in E.2.6 – Consistency Model: Query vs Webhook.