Overview

This section consolidates practical implementation guidelines for building robust SIBS Payment Gateway (SPG) integrations.

It focuses on how to implement the concepts defined in previous sections, ensuring:

• Correct handling of asynchronous flows
• Consistent transaction state management
• Resilient behavior under real-world conditions

The emphasis is on operational reliability, not on API usage details.

Error classification and handling strategies are defined in C.5 – Status Codes and Error Codes Mapping and its subchapters.

For the underlying asynchronous lifecycle and consistency model, refer to F.3.4 – Asynchronous and Consistency Scenarios.

Adopt a State-Driven Design

Integrations must be designed around persistent transaction state transitions rather than isolated request/response interactions.

Guidelines

• Model transactions using states such as:
  • Pending, Success, Declined, Timeout
• Persist state transitions explicitly
• Ensure state transitions are:
  • Deterministic
  • Forward-only

Rationale

SPG is inherently asynchronous and event-driven, making state-based modeling essential for correctness.

Separate Technical and Business Logic

Maintain a strict separation between:

• Technical processing
• Business actions

Guidelines

• Use returnStatus for:
  • API validation
  • Technical success/failure
• Use paymentStatus for:
  • Business decisions
  • Transaction outcome
• Never trigger business actions based solely on:
  • HTTP status
  • returnStatus.statusCode

Treat Pending as a First-Class State

Pending is a normal and expected state, not an exception.

Guidelines

• Always support Pending in:
  • Persistence model
  • Business workflows
• Design processes to:
  • Wait for final confirmation
  • Handle long-lived pending states

Rationale

Many payment methods (e.g., MB WAY, Multibanco Reference) rely on external or delayed confirmation.

Use Webhooks and Status Inquiry Complementarily

Do not rely exclusively on a single mechanism.

Guidelines

• Use webhooks for:
  • Real-time updates
  • Event-driven processing
• Use the Status Inquiry (GET <ROOT_URL>/payments/{transactionID}/status) for:
  • Final state confirmation
  • Recovery from missed or delayed events

For webhook delivery semantics, retry behavior, payload validation, and security recommendations, refer to E.1 – Webhooks (Notifications).

Implement Idempotent Processing

All transaction processing must be idempotent by design.

Guidelines

• Ensure that:
  • The same event can be processed multiple times safely
• Use identifiers such as:
  • transactionID
  • merchantTransactionId
• Protect against:
  • Duplicate webhook deliveries
  • Retried operations

Rationale

Distributed systems cannot guarantee single delivery.

Enforce Safe State Transitions

Prevent invalid or inconsistent state changes.

Guidelines

• Do not allow transitions such as:
  • Success → Pending
  • Declined → Pending
• Define and protect terminal business states such as:
  • Success
  • Declined
• Reject updates that attempt to overwrite final states

Design for Eventual Consistency

Assume that systems are temporarily inconsistent.

Guidelines

• Do not assume:
  • Immediate synchronization between systems
• Expect:
  • Delayed updates
  • Out-of-order events
• Validate final state using Status Inquiry when no final webhook is available or when confirmation, recovery, or reconciliation is required (GET <ROOT_URL>/payments/{transactionID}/status)

Implement Reconciliation Mechanisms

Reconciliation is mandatory for production systems.

Guidelines

• Periodically query transactions in:
  • Pending
  • Timeout
• Detect and resolve:
  • Missing updates
  • Inconsistent states
• Maintain audit logs for:
  • All state transitions

Handle Timeouts and Uncertain States Properly

Timeout represents an uncertain state and must not be interpreted as final failure without validation.

Guidelines

• Treat Timeout as:
  • Uncertain state
• Always:
  • Confirm via the Status Inquiry (GET <ROOT_URL>/payments/{transactionID}/status) when required
  • Delay business decisions until resolved

Ensure Observability and Traceability

Visibility is essential for debugging and operations.

Guidelines

• Log:
  • Requests and responses
  • Webhook payloads
  • State transitions
• Correlate using:
  • transactionID
  • merchantTransactionId
• Ensure logs support:
  • Debugging
  • Audit and reconciliation

Control Retry Strategies Carefully

Retries must be intentional and controlled.

Guidelines

• Retry only when errors are classified as temporary (statusCode = Txxxx) or retryable according to the applicable SPG status and error semantics.
• Avoid:
  • Blind retries
  • Duplicate transaction creation
• Use:
  • Backoff strategies
  • Status Inquiry checks (GET <ROOT_URL>/payments/{transactionID}/status)

Summary

Robust SPG integrations require:

• State-driven design
• Strict separation of concerns
• Idempotent and resilient processing
• Explicit handling of asynchronous behavior

By applying these practices, integrators ensure:

• Reliable transaction processing
• Accurate financial outcomes
• Stability under real-world operational conditions