Overview

This section provides a complete, end-to-end example of how webhook notifications are integrated into the transaction lifecycle, including reception, processing, and reconciliation with the authoritative transaction state.

The objective is to demonstrate how asynchronous notifications, API interactions, and internal processing must be combined to produce consistent and correct transaction outcomes in a production-grade SIBS Payment Gateway (SPG) integration.

End-to-End Scenario Description

The following scenario represents a typical asynchronous payment flow:

1. A checkout is created
2. The payment method is executed
3. The transaction enters an intermediate or pending state
4. A webhook notification is received with an updated state
5. The merchant system processes the notification
6. The final transaction state is confirmed using the Status API

This model applies across multiple payment methods where the final outcome is not immediately available at the time of the initial request.

End-to-End Processing Flow

This flow illustrates how webhook processing and status validation must be combined to ensure correct transaction state handling.

Step-by-Step Processing Model

Step 1 – Transaction Initiation

The merchant initiates the transaction through a checkout request and executes the selected payment method.

At this stage:

• A transactionID is generated
• The transaction may not reach a final state immediately
• Further updates are expected through webhook notifications

Step 2 – Webhook Reception and Processing

When the transaction state changes, SPG sends a webhook notification.

The merchant system must:

• Receive the notification
• Validate headers and structure
• Decrypt and parse the payload
• Extract:
  • transactionID
  • notificationID
  • relevant state information

The notification must then be processed using the model described in F.10.1 Webhook Reception, Decryption and Processing Flow.

Step 3 – Idempotent Event Handling

Before executing any business logic, the system must ensure idempotency:

• Check whether notificationID has already been processed
• Prevent duplicate execution of business logic
• Ensure safe handling of repeated notifications

At this stage, the notification is treated as an event signal, not as final confirmation.

Step 4 – Status Reconciliation

After processing the webhook, the system must confirm the authoritative transaction state.

Call:

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

The response provides:

• Final paymentStatus
• Authoritative transaction outcome
• Complete transaction data

This step is mandatory to ensure authoritative consistency of the transaction state between:

• event-driven updates (webhooks)
• system-of-record state (Status API)

Step 5 – Internal State Update

Based on the Status API response, the merchant system must:

• Update internal transaction records
• Apply business logic based on the final state
• Trigger downstream processes if required

Examples:

• Mark order as paid
• Trigger fulfillment
• Record failure or retry logic

The system must rely on the status response, not solely on the webhook payload.

State Consistency Model

Webhook notifications and Status API responses represent two complementary views of transaction state:

• Webhooks provide event-driven updates
• Status API provides authoritative state validation

These two mechanisms must be combined to ensure:

• correct interpretation of transaction outcomes
• resilience to delayed or duplicated events
• consistency across distributed systems

Example Flow (Conceptual)

Webhook received:
  paymentStatus = "Success"
  transactionID = "tx123"
  notificationID = "notif001"

Process:
  - Check idempotency (notif001)
  - Accept event

Call Status API:
  GET /api/v2/payments/tx123/status

Response:
  paymentStatus = "Success"

Result:
  - Update order status to PAID
  - Persist final transaction state

This example illustrates the combination of webhook-driven processing and status-based validation.

Handling Non-Final States

Webhook notifications may represent intermediate states such as:

• Pending
• InProcessing

In these cases:

• The system must not assume final outcome
• Status validation may need to be retried
• Business actions must be deferred until a final state is confirmed

This behavior is critical for payment methods with delayed or user-driven completion.

Failure and Retry Considerations

During the end-to-end flow, the system must handle:

• duplicate webhook notifications
• delayed delivery
• temporary inconsistencies between webhook and status
• transient failures in API calls

Correct behavior requires:

• idempotent processing
• retry mechanisms for status validation
• controlled state transitions
• no reliance on a single signal

Final Consideration

A correct SPG integration must treat webhook notifications and status validation as complementary components of a unified processing model.

Webhook notifications provide timely visibility into transaction events, while the Status API provides the authoritative confirmation required for final decision-making.

By combining these mechanisms as illustrated in this section, integrators ensure that transaction handling remains:

• consistent
• reliable
• resilient under asynchronous conditions

This approach guarantees correct behavior across all transaction scenarios and lifecycle states, regardless of timing, delivery order, or external dependencies.