Overview

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

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

These mechanisms serve different purposes and must be used together to ensure consistency, reliability, and correctness in transaction processing.

Conceptual Model

Webhooks

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

Status API

• On-demand query mechanism
• Returns the current and authoritative state of the transaction

Consistency Principle

Webhooks act as event triggers, while the Status API provides the source of truth.

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 must always validate the transaction state using the Status API before applying critical business decisions.

Critical Implementation Rule

The webhook endpoint must respond immediately and must not perform synchronous calls to the SPG API.

Do NOT:

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

Recommended Processing Model

The correct implementation pattern is asynchronous.

Sequence Diagram

Status API Endpoint

GET https://spg.qly.site1.sibs.pt/api/v2/payments/{transactionID}/status

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

• Final state validation
• Reconciliation
• Recovery from missed or delayed events

When to Use Each Mechanism

Use Webhooks to:

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

Use Status API to:

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

Typical Scenarios

Asynchronous Payment Flow

Webhooks notify that the transaction has evolved, but the Status API must be used to confirm whether the transaction is successful, pending, or failed.

Duplicate or Out-of-Order Webhooks

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

Missing Webhooks

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

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
• Always validate transaction state using the Status API
• Implement idempotent processing
• Log both webhook and status interactions

Summary

Webhooks and the Status API are complementary:

• Webhooks provide event notification
• Status API provides the authoritative state

A correct implementation requires:

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

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