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 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 API

GET https://spg.qly.site1.sibs.pt/api/v2/payments/{transactionID}/status

Characteristics

• returns current authoritative state
• reflects the latest known status of the transaction

Authoritative Source Principle

The Status API must always be considered the source of truth.

Rule

Status API > Webhook > Initial API Response

Implication

• Webhooks are notifications, not guarantees of final state
• Initial API responses are never final
• Only the Status API provides reliable final confirmation

Reconciliation Scenarios

1. Webhook vs Status Mismatch

Scenario

• Webhook indicates:
  • paymentStatus = Success
• Status API returns:
  • paymentStatus = Pending

Interpretation

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

Action

• trust Status API
• retry status query after short delay

2. Status Ahead of Webhook

Scenario

• Status 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

4. Out-of-Order Webhooks

Scenario

• receive:
  • Pending
  • then Success
  • then another Pending

Interpretation

• delivery order not guaranteed

Action

• always compare with:
  • current stored state
  • Status API
• never downgrade state

5. Missing Webhooks

Scenario

• no webhook received

Interpretation

• delivery failure or configuration issue

Action

• rely on Status 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 API

GET https://spg.qly.site1.sibs.pt/api/v2/payments/{transactionID}/status

Step 3 – Compare States

• compare:
  • received state
  • status 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 regress from a more advanced state to a previous state.

Examples

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

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

Operational Rules

Rule 1 – Never trust a single source

• always reconcile

Rule 2 – Status API is authoritative

• final decisions must rely on it

Rule 3 – Webhooks are triggers

• not final confirmation

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:

• reconcile all states using Status API
• 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

The Status API must always be treated as the authoritative source of truth, with webhooks serving as event notifications that trigger reconciliation.