Overview

A frequent integration pitfall in SIBS Payment Gateway (SPG) implementations is the failure to correctly handle the full transaction lifecycle.

This occurs when transactions are treated as isolated events rather than as stateful processes that evolve over time. As a result, systems may correctly execute individual API calls but fail to maintain consistency across the complete lifecycle of the payment.

In SPG, every transaction progresses through a sequence of states and operations that must be explicitly managed and correlated. Ignoring this lifecycle leads to inconsistent transaction states and incorrect business outcomes.

Nature of the Lifecycle

SPG transactions are not single-step operations. Depending on the payment method and flow, a transaction may include:

• Checkout creation
• Payment execution or authorization
• Intermediate states (e.g., Pending)
• Final state transition (e.g., Success, Declined, or another final paymentStatus)
• Post-processing actions (e.g., CAPTURE, REFUND, or reconciliation)

In certain models, such as two-step payments, the lifecycle is explicitly split across multiple operations:

• AUTH (authorization)
• CAPTURE (funds capture)

See also D.3 – Two-Step Payments for the operational flow definitions and processing model associated with AUTH and CAPTURE operations.

Each step represents a distinct and controlled stage in the lifecycle and skipping or misinterpreting any of them leads to incorrect system behavior.

The Core Pitfall

The core issue arises when integrations:

• Treat transactions as completed after a single step
• Ignore intermediate or follow-up operations
• Fail to track and persist state transitions over time
• Do not enforce valid sequencing between operations

A typical incorrect assumption is:

“Once the payment request is successful, no further action is required.”

This assumption is invalid in SPG integrations, particularly for:

• asynchronous payment methods
• two-step payment models
• scenarios requiring post-processing actions

Incorrect Implementation Patterns

Incomplete lifecycle handling typically manifests through the following patterns:

• Processing only the initial payment step and ignoring subsequent required actions
• Not implementing CAPTURE after a successful AUTH in two-step flows
• Treating a successful authorization (AUTH) as final settlement
• Ignoring transitions between intermediate and final states
• Failing to update internal systems when transaction state evolves
• Not handling post-payment operations such as refunds or reversals

These issues result from a fragmented view of the transaction, where individual steps are implemented correctly but not connected into a coherent lifecycle.

Correct Lifecycle Handling Model

A correct implementation must treat each transaction as a controlled lifecycle, where:

• Each state transition is explicitly tracked
• Each operation is executed in the correct sequence
• The system maintains continuity between all stages

This requires:

• Persisting key identifiers (e.g., transactionID and merchant.merchantTransactionId) across all steps
• Tracking transaction state over time, not just at a single point
• Using Inquiry Details when extended transaction lifecycle visibility or operation-level diagnostics are required
• Ensuring that operations such as AUTH, CAPTURE, REFUND, and status validation are correctly sequenced
• Preventing invalid transitions (e.g., CAPTURE without AUTH, or repeated operations)

As defined in C.3 – Transaction States and C.4 – Transaction State Transition Model, transaction states must be treated as part of a controlled state machine, not as independent flags.

Additional lifecycle visibility and operation-level transaction diagnostics may require the use of Inquiry Details, as described in E.2.10 – Inquiry Details API.

Relationship with Asynchronous Processing

Incomplete lifecycle handling is often compounded by asynchronous behavior.

Because transaction states may evolve over time:

• intermediate states must be tracked
• updates received through webhook notifications or Status Inquiry must be correctly applied
• systems must remain consistent across delayed transitions

Ignoring lifecycle management in an asynchronous context leads to:

• stale or incorrect internal states
• missed transitions
• inconsistent reconciliation outcomes

See E.1 – Webhooks (Notifications) and E.2 – Status Inquiry / Get Status for the mechanisms used to monitor transaction lifecycle evolution and confirm or reconcile transaction state when required.

Consequences of Incomplete Lifecycle Handling

Failure to manage the full transaction lifecycle leads to high-impact issues:

• Authorized payments that are never captured
• Financial reporting inaccuracies and reconciliation gaps
• Duplicate or invalid operations
• Inconsistent transaction histories across systems
• Incorrect handling of refunds or post-payment operations

These issues are particularly critical in production environments, where lifecycle gaps directly affect financial accuracy and operational reliability.

Key Principle

A transaction in SPG must be treated as a stateful lifecycle, not as a single operation.

Correct behavior requires:

• explicit tracking of state transitions
• enforcement of valid operation sequences
• continuous alignment between system state and transaction evolution

Any integration that does not manage the full lifecycle of a transaction will produce incomplete, inconsistent, and unreliable outcomes.