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 validated transaction-state outcome.

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 transaction-state outcome is confirmed using Status Inquiry / Get Status when confirmation or reconciliation is required

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 asynchronous event signal, not as final confirmation.

Step 4 – Status Reconciliation

After processing the webhook, the system should confirm or reconcile the transaction-state outcome when required.

Call:

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

The response provides:

• Final paymentStatus
• Latest transaction outcome available through Status Inquiry / Get Status
• Complete transaction data

This step is used when confirmation, recovery, or inconsistency resolution is required of transaction-state interpretation between:

• event-driven updates (webhooks)
• latest transaction state available through Status Inquiry / Get Status

Step 5 – Internal State Update

Based on the Status Inquiry 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 Inquiry responses represent two complementary transaction-state perspectives within the lifecycle orchestration model:

• Webhooks provide event-driven updates
• Status Inquiry / Get Status provides transaction-state confirmation and reconciliation when required

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 Inquiry:
  GET /payments/tx123/status

Response:
  paymentStatus = "Success"

Result:
  - Update order status to PAID
  - Persist validated transaction-state outcome

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

When extended operational diagnostics are required during reconciliation analysis or lifecycle troubleshooting, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.

Handling Non-Final States

Webhook notifications may represent intermediate states such as:

• Pending

In these cases:

• The system must not assume final outcome
• Transaction-state confirmation or reconciliation 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

Retry decisions must be based on error classification, where temporary conditions (statusCode = Txxxx) allow controlled retries, while validation or business errors (statusCode = Exxxx) must not be retried automatically.

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 asynchronous visibility into transaction events, while Status Inquiry / Get Status provides confirmation and reconciliation support when 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.