Transaction lifecycle (Beta)

The Issuing transaction APIs use three levels of categories to represent card payment activity: lifecycles, card transactions, and transaction events. Understanding this model is important when you reconcile transactions, handle inquiries and disputes, or build reporting and operations workflows, as it helps you choose the right API and interpret statuses and fund movements correctly.

Three-level transaction model

Airwallex structures transaction data in three layers, from the broadest (network-level grouping) to the most granular (individual events):

• Lifecycles have no status; matching is best-effort and depends on the network and acquirers. A lifecycle can include matched refunds and does not have a guaranteed terminal state.
• Card transactions always reach a terminal state (CLEARED, REVERSED, EXPIRED, DECLINED, or VERIFIED). When an authorization is fully cleared, expired, or reversed, no further events are added to that card transaction. Refunds always form a new card transaction but can be linked via lifecycle_id.
• Transaction events have no status; each event has a lifecycle_id and card_transaction_id so you can trace it to its containers.

Lifecycle

A lifecycle groups related card transactions and transaction events. It begins with a network message represented as a transaction event.

Typical first messages include:

• Authorization request (most common) - when a merchant requests approval to use the card.
• Financial transactions - standalone financial messages such as ATM withdrawals or forced captures.
• Refunds - unmatched refunds start a new lifecycle; matched refunds attach to an existing lifecycle.

With a lifecycle_id, you can retrieve the related card transaction IDs and transaction event IDs. Matching is done on a best-effort basis and depends on the network and acquirers providing the identifiers Airwallex needs.

Billing amounts aggregation

The billing_amounts object in the API holds aggregated totals that are updated as transaction events arrive. It appears at two levels: lifecycle (rolled up across everything on that lifecycle) and card transaction (amounts for a single card transaction).

At the lifecycle level: billing_amounts aggregates amounts across all card transactions and transaction events that belong to that lifecycle. One lifecycle can span multiple card transactions (for example, a purchase and a later refund). The lifecycle-level aggregation gives you a single view of total authorized, debited, credited, declined, expired, pending, and reversed amounts for the whole payment story, so you can reconcile or display net position without summing individual card transactions yourself.

At the card transaction level: billing_amounts aggregates amounts only for that single card transaction. It is an up-to-date snapshot of the totals for every transaction event in that card transaction (authorizations, clearings, reversals). Use it to derive the card transaction status and to understand how much is reserved, debited, or credited for that transaction alone.

The following fields appear in billing_amounts (at either level, with the same meaning):

Card transaction

A card transaction groups related transaction events and represents Airwallex's interpretation of one card transaction. It usually starts with a network message as well.

Typical first messages include:

• Authorization request (most common) - when a merchant requests approval to use the card.
• Financial transactions - when there is no matching outstanding authorization, or the matching authorization has been fully cleared or reversed; a new card transaction is created.
• Refunds - every refund (both matched and unmatched) is a new card transaction.

Later messages that attach to the same card transaction include:

• Incremental authorization - increase to the authorized amount.
• Single or multiple financial transaction advices - single or multi-capture clearing.
• Reversal request - cancellation of a previously approved authorization (release of the reserve).

Each card transaction has exactly one lifecycle_id. Multiple card transactions can share the same lifecycle_id, indicating they are related (for example, original purchase and refund).

Billing amounts aggregation applies to both lifecycles and card transactions. The following subsections focus on card transaction behavior: status, fund direction, and how status changes are determined using fund direction and billing totals.

Card transaction statuses

Only card transactions have a status. Possible statuses and whether they are terminal are:

Fund direction

Each card transaction includes a fund direction that describes the intended movement of funds relative to the wallet.

How state changes are determined

Card transaction state changes are determined by fund direction. Billing amounts aggregation totals (total_pending, total_debited, total_credited, total_expired, total_reversed) show when a transition occurs. The statuses CLEARED, EXPIRED, REVERSED, DECLINED, and VERIFIED are terminal (no further transitions).

When fund direction is DEBIT

This section is for card transactions whose fund direction is DEBIT (funds intended to move out of the wallet). It lists which status values can appear and how status and billing amounts change when authorization, clearing, expiry, reversal, or decline events occur.

Allowed statuses

AUTHORIZED, CLEARED, EXPIRED, REVERSED, DECLINED.

Transition rules

When fund direction is CREDIT

This section is for card transactions whose fund direction is CREDIT (funds intended to move into the wallet). It lists which status values can appear and how status and billing amounts change for credit authorizations, clearing, reversals, or declines.

Allowed statuses

AUTHORIZED, DECLINED, CLEARED, REVERSED.

Transition rules

When fund direction is NO_MOVEMENT

This section is for card transactions whose fund direction is NO_MOVEMENT (no intended wallet movement). It lists which status values can appear and how status and billing amounts change for declines or verification-only flows.

Allowed statuses

DECLINED, VERIFIED.

Transition rules

Transaction events and scenarios

Each transaction event has a type and optional subtype. Together with card transaction status and transaction_category, they describe the full payment story.

For reference tables (event types, fund movement mapping, transaction_category values) and step-by-step example flows (dual message, partial clearing, refunds, reversal clearing), see:

• Transaction events and categories
• Transaction scenarios

Real lifecycles can be more complex, with multiple authorizations, partial clearings, and reversals on the same lifecycle_id.

See also

• Retrieve lifecycle and transaction data
• Retrieve card transactions
• Transaction events and categories
• Transaction scenarios
• Transaction lifecycle (older API versions)