Overview

Reconciliation is the process of ensuring consistency between observed transaction events and the transaction state retrieved through Status Inquiry APIs when required.

Due to the event-driven and eventually consistent nature of the SIBS Payment Gateway, discrepancies may occur between:

• Webhook notifications received by the merchant
• Transaction state retrieved via Status Inquiry

Reconciliation patterns define how integrators must detect, evaluate, and resolve these discrepancies to ensure correct and reliable transaction processing.

Reconciliation strategies must be implemented in accordance with the consistency model defined in E.2.6 – Consistency Model: Query vs Webhook.

Reconciliation Objectives

Reconciliation mechanisms must ensure:

• Accurate determination of the final transaction state
• Detection of missing or delayed webhook events
• Prevention of duplicate or inconsistent business actions
• Alignment between internal system state and SIBS transaction state
• Reconciliation must ensure that business actions are executed exactly once, even in the presence of duplicated events or inconsistent intermediate states.

Core Reconciliation Principles

• The Status Inquiry APIs provide the latest transaction state available through the query API
• Webhooks must be treated as event notifications and may contain a final paymentStatus
• Reconciliation must be idempotent and repeatable
• Only appropriately validated final states must trigger irreversible business actions
• Error and Timeout states may still require operational reconciliation or asynchronous validation depending on the payment method and transaction lifecycle stage.
• Systems must tolerate temporary inconsistencies

Reconciliation Triggers

Reconciliation should be triggered in the following situations:

• Upon receiving a webhook notification
• When polling detects a state change
• When a timeout or delay threshold is exceeded
• During scheduled reconciliation processes (batch jobs)
• When inconsistencies are detected internally

Real-Time Reconciliation Pattern

This pattern is applied during active transaction flows.

Flow

1. Receive webhook notification
2. Extract transaction identifier
3. Call Status Inquiry APIs
4. Retrieve latest transaction state available through the query API
5. Compare webhook data with Status Inquiry APIs state
6. Apply business logic based on the final webhook state or on Status Inquiry validation when required

Key Characteristics

• Ensures immediate validation of events
• Prevents acting on outdated or inconsistent webhook data
• Supports real-time user experience flows

Polling-Based Reconciliation Pattern

This pattern is used when webhooks are delayed or unavailable.

Flow

1. Initiate transaction
2. Start polling according to defined strategy
3. Retrieve transaction state periodically
4. Detect transition to final state
5. Trigger appropriately validated business action

Key Characteristics

• Provides fallback mechanism
• Ensures eventual resolution even without webhooks
• Must respect polling limits and backoff strategies

Polling strategies, backoff models, and stop conditions are described in E.2.5 – Polling Strategy and Best Practices.

Deferred (Batch) Reconciliation Pattern

This pattern is used for audit and recovery scenarios.

Flow

1. Identify transactions in non-final or uncertain state
2. Execute batch Status Inquiry APIs requests
3. Retrieve latest transaction states available through the query API
4. Compare with internal records
5. Detect and correct inconsistencies
6. Trigger missing business actions if required

Key Characteristics

• Supports eventual consistency across systems
• Handles missed events or processing failures
• Typically executed on a scheduled basis

Reconciliation Decision Model

Condition	Action
Webhook received	Validate state via the Status Inquiry APIs
Status Inquiry APIs indicate a typically final state	Proceed with appropriately validated business action
Webhook and query differ	Use the Status Inquiry APIs to retrieve the latest transaction state available through the query API and resolve the inconsistency
No webhook received	Use polling or batch reconciliation
Transaction remains non-final beyond expected time	Escalate or retry

Handling Inconsistent States

Transient and final state interpretation semantics are described in E.2.4 – Status Semantics and Interpretation.

Scenario: Webhook state differs from queried state

• Use the Status Inquiry APIs to retrieve the latest transaction state available through the query API and resolve the inconsistency
• Ignore outdated webhook data

Scenario: Webhook state and queried state differ temporarily

• Treat as transient inconsistency
• Continue polling until resolved

Scenario: Query indicates final state, webhook missing

• Proceed with appropriately validated business action
• Log missing webhook for monitoring

Scenario: Duplicate webhook received

• Ensure idempotent processing
• Do not re-trigger business actions

State Transition Validation

Reconciliation must ensure that state transitions are valid and expected.

Guidelines:

• Prevent regression to earlier states
• Validate transitions against known lifecycle patterns
• Ignore inconsistent or outdated transitions

Idempotency Requirements

All reconciliation logic must be idempotent:

• Processing the same event multiple times must produce the same result
• Business actions must not be executed more than once
• State updates must be safe to repeat

Error Handling in Reconciliation

• Retry the Status Inquiry APIs on transient failures
• Log and monitor inconsistencies
• Escalate unresolved discrepancies
• Implement alerting for abnormal patterns

Observability and Monitoring

Reconciliation processes must be observable:

• Log all reconciliation decisions
• Track discrepancies between webhook and query
• Monitor missing webhook events
• Measure reconciliation latency

Integration Anti-Patterns

The following practices must be avoided:

• Acting directly on webhook data without validation
• Ignoring reconciliation for long-running transactions
• Assuming webhook completeness or reliability
• Failing to implement fallback mechanisms
• Triggering business actions multiple times

Key Integration Principles

• Reconcile webhook data with the Status Inquiry APIs when no final webhook is available, when states differ, or when additional confirmation is required
• Design for eventual consistency
• Ensure idempotent processing
• Implement both real-time and batch reconciliation
• Monitor and handle discrepancies proactively

Summary

Reconciliation patterns ensure that transaction processing remains accurate, consistent, and reliable despite the asynchronous and distributed nature of the system.

By combining:

• Webhook-driven event handling
• Status Inquiry APIs-based validation
• Polling and batch reconciliation mechanisms

Integrators can achieve:

• Correct final state determination
• Resilient and fault-tolerant processing
• Consistent alignment between systems

These patterns are essential for building robust, enterprise-grade payment integrations within the SIBS Payment Gateway ecosystem.