Transactions Lifecycle

Infrarails transactions follow a defined lifecycle.

A transaction's status indicates whether it is awaiting processing, currently being processed, completed, rejected, or voided.

Understanding these states is essential for building reliable financial workflows.

Transaction statuses

The core transaction engine supports five statuses.

Lifecycle diagram

flowchart TD
    A["PENDING"] --> B["INFLIGHT"]
    A --> C["COMPLETED"]
    A --> D["REJECTED"]
    A --> E["VOID"]

    B --> C
    B --> D
    B --> E

    classDef pending fill:#fef3c7,stroke:#d97706,color:#92400e
    classDef processing fill:#dbeafe,stroke:#2563eb,color:#1d4ed8
    classDef completed fill:#dcfce7,stroke:#16a34a,color:#166534
    classDef rejected fill:#fee2e2,stroke:#dc2626,color:#991b1b

    class A pending
    class B processing
    class C completed
    class D,E rejected

Supported transitions

COMPLETED, REJECTED, and VOID are terminal states in this lifecycle model.

PENDING

A transaction in the PENDING state has been created but has not reached a final processing outcome.

Depending on the workflow, it may be awaiting additional processing, validation, or approval.

Applications should not interpret a pending transaction as completed financial activity.

INFLIGHT

A transaction in the INFLIGHT state is being processed.

This state can be useful for workflows involving asynchronous operations or external dependencies.

An inflight transaction may subsequently become completed, rejected, or voided.

COMPLETED

A COMPLETED transaction represents finalized financial activity.

Applications can use this state to distinguish finalized transactions from operations still in progress.

The associated balance effects must be interpreted according to the ledger's posting rules.

REJECTED

A REJECTED transaction represents an operation that has been rejected.

Applications should retain the transaction identifier and relevant error or rejection information where available.

A rejected transaction should not be treated as successfully completed.

VOID

A VOID transaction represents an operation that has been voided before successful finalization.

Voiding a transaction is distinct from reversing a previously completed transaction.

Completed financial activity generally requires an appropriate compensating operation rather than an unsupported lifecycle transition.

Example: Internal transfer

Consider an application transferring €75.00 between two accounts.

The workflow might be:

1. Application creates a transaction
             |
             v
2. Transaction status: PENDING
             |
             v
3. Transaction enters processing
             |
             v
4. Transaction status: INFLIGHT
             |
             v
5. Processing succeeds
             |
             v
6. Transaction status: COMPLETED

The core lifecycle also permits direct transition from PENDING to COMPLETED.

The example above illustrates a possible workflow, not a requirement that every transaction must pass through INFLIGHT.

Example: Rejected transaction

A transaction may be rejected during processing.

PENDING
   |
   v
INFLIGHT
   |
   v
REJECTED

Applications should handle rejection as a terminal outcome and provide appropriate user-facing information.

Handling asynchronous operations

Applications should be designed to handle transactions that do not finalize immediately.

Depending on the integration, transaction status may be retrieved through API requests or communicated through supported event mechanisms.

Do not assume that webhooks or status polling are universally available for every operation.

Lifecycle and idempotency

A network timeout during transaction creation does not necessarily mean the transaction was not created.

Applications should use the documented idempotency mechanism and check for an existing transaction before submitting another logical operation.

This reduces the risk of duplicate financial movements.

Best practices

• Track transactions by their unique identifiers.
• Distinguish processing states from terminal states.
• Do not assume every transaction passes through INFLIGHT.
• Avoid treating PENDING as finalized.
• Handle REJECTED and VOID outcomes explicitly.
• Preserve transaction references for reconciliation.
• Use idempotency for eligible operations.
• Never assume that a completed transaction can be modified through another status transition.

Next steps

Continue with the Platform Capabilities documentation:

• Transfers
• Payments
• Fees
• Provider Integrations
• Webhooks
• Reconciliation