Overview

Reconciliation is the process of ensuring consistency between observed transaction events and the authoritative transaction state.

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 endpoint is the authoritative source of truth
• Webhooks must be treated as event triggers, not final state indicators
• Reconciliation must be idempotent and repeatable
• Only final states must trigger irreversible business actions
• 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 endpoint
4. Retrieve current transaction state
5. Compare webhook data with queried state
6. Apply business logic based on queried state

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 business action

Key Characteristics

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

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 requests
3. Retrieve latest transaction states
4. Compare with internal records
5. Correct inconsistencies
6. Trigger missing business actions if required

Key Characteristics

• Ensures 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 Status Inquiry
Status Inquiry indicates final state	Proceed with business logic
Webhook and query differ	Trust Status Inquiry
No webhook received	Use polling or batch reconciliation
Transaction remains non-final beyond expected time	Escalate or retry

Handling Inconsistent States

Scenario: Webhook state differs from queried state

• Always trust Status Inquiry
• Ignore outdated webhook data

Scenario: Webhook indicates final state, but query does not

• Treat as transient inconsistency
• Continue polling until resolved

Scenario: Query indicates final state, webhook missing

• Proceed with 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 Status Inquiry 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

• Always reconcile webhook data with Status Inquiry
• 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-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.