Overview

This section defines how to reconcile transaction state information obtained from different sources in the SIBS Payment Gateway (SPG), namely:

• synchronous API responses
• webhook notifications
• Status Inquiry API queries

Its objective is to ensure that merchant systems:

• correctly interpret potentially inconsistent or out-of-order information
• avoid incorrect business decisions based on intermediate states
• maintain a consistent and reliable view of transaction status

Multiple Sources of State Information

Transaction state may be obtained from three distinct sources:

1. Synchronous API Response

Returned immediately after initiating an operation (e.g., checkout creation or payment request).

Characteristics

• reflects initial or intermediate state
• often:
  • paymentStatus = Pending
• does not represent final outcome

2. Webhook Notifications

Sent asynchronously by SPG to notify state changes.

Characteristics

• event-driven
• may represent:
  • intermediate states
  • final states
• may be delivered:
  • with delay
  • out of order
  • more than once

3. Status Inquiry API

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

Characteristics

• returns the current transaction state known by SPG
• reflects the latest known status of the transaction

Complementary Source Principle

• Webhook notifications and Status Inquiry responses are complementary mechanisms
• Valid final-state webhooks should be processed as transaction-state updates
• Status Inquiry should be used for explicit verification, recovery, missed webhooks, delayed processing, or operational reconciliation
• Initial API responses may represent an initial or intermediate transaction state

Business actions must only be triggered after reconciliation confirms a final transaction state.

Figure – Transaction State Reconciliation Model

Reconciliation Scenarios

1. Webhook vs Status Mismatch

Scenario

• Webhook indicates:
  • paymentStatus = Success
• Local merchant state is still Pending

Interpretation

• webhook may be:
  • delayed
  • out of order
• or system still processing

Action

• process valid final-state webhooks idempotently
• compare the webhook state with the stored transaction state
• use Status Inquiry only when explicit verification or recovery is required
• never downgrade a transaction from a final state to a non-final or previous state

2. Status Ahead of Webhook

Scenario

• Status Inquiry API returns:
  • paymentStatus = Success
• no webhook received yet

Interpretation

• webhook delivery delayed

Action

• proceed with business logic
• still process webhook when received (idempotently)

3. Duplicate Webhooks

Scenario

• same webhook received multiple times

Interpretation

• normal SPG behavior (retry mechanism)

Action

• process idempotently
• ignore duplicates

Webhook retries are expected behavior and must not be treated as integration failures.

4. Out-of-Order Webhooks

Scenario

• a later notification reports an older or less advanced state than the state already stored by the merchant system

Interpretation

• the notification is stale, duplicated, delayed, or delivered out of order

Action

• compare the incoming state with the current stored transaction state
• preserve monotonic state progression
• use Status Inquiry only when explicit verification or recovery is required
• never downgrade a transaction from a final state to a non-final or previous state

5. Missing Webhooks

Scenario

• no webhook received

Interpretation

• delivery failure or configuration issue

Action

• rely on Status Inquiry API polling
• implement fallback polling mechanism

State Reconciliation Strategy

Merchant systems must implement a deterministic reconciliation strategy.

Step 1 – Receive Event (API or Webhook)

• extract:
  • transactionID
  • paymentStatus

Step 2 – Query Status Inquiry API

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

Step 3 – Compare States

• compare:
  • received state
  • status Inquiry API state

Step 4 – Apply State Rules

• accept only:
  • same or forward state transitions
• reject:
  • backward transitions

Step 5 – Persist Final State

• update transaction record
• trigger business logic only if:
  • state is final

State Progression Rule

Transaction states must follow monotonic progression.

Rule

A transaction state must never transition from a more advanced state to a previous state.

Examples

• Pending → Success → valid
• Success → Pending → invalid (must be ignored)

For the formal transaction state transition model and allowed transitions, refer to C.4 – Transaction State Transition Model.

Idempotency Requirements

All reconciliation logic must be idempotent.

Requirements

• repeated webhook processing must not:
  • duplicate operations
  • trigger repeated business actions
• state updates must be:
  • conditional
  • based on current stored state

Polling Strategy (Fallback)

When webhook reliability cannot be guaranteed:

Recommended Approach

• poll Status Inquiry API:
  • immediately after initial request
  • periodically while in non-final state

Example

• poll every:
  • 5–10 seconds (short-lived flows)
  • longer intervals for long-running flows

Stop Condition

• stop polling when:
  • final state is reached

Polling frequency should be adapted to the payment method and transaction lifecycle characteristics.

Polling retries and fallback mechanisms must follow the retry and error handling principles defined in C.6 – Error Payloads and Handling Guidelines.

Operational Rules

Rule 1 – Never trust a single source

• always reconcile

Rule 2 – Use Status Inquiry for verification and recovery

• use it when the current transaction state must be explicitly queried

Rule 3 – Process valid final-state webhooks

• webhooks may provide final transaction-state updates and must be handled idempotently

Rule 4 – Never act on non-final states

• only act on:
  • Success
  • Declined
  • Error
  • Timeout

Rule 5 – Always implement idempotency

• avoid duplicate processing

Implementation Checklist

Merchant systems must:

• use Status Inquiry API for verification, recovery, missed webhooks, delayed processing, or operational reconciliation
• implement idempotent webhook processing
• handle duplicate and out-of-order events
• ensure monotonic state progression
• implement fallback polling
• trigger business logic only on final states

Summary

SPG operates in an asynchronous, distributed model, where transaction state may be:

• delayed
• duplicated
• delivered out of order

Correct reconciliation ensures:

• consistent and reliable transaction state
• prevention of incorrect business decisions
• resilience to integration and network issues
• robust and predictable payment processing

Status Inquiry API and webhooks must be used as complementary mechanisms. Valid final-state webhooks must be processed idempotently, while Status Inquiry supports verification, recovery, and reconciliation when needed.