Card Transaction Lifecycle

Every card transaction moves through the same fundamental lifecycle: authorization, clearing, and settlement, with disputes as a possible fourth phase. Understanding this lifecycle is foundational to everything else in this documentation: it explains why a transaction can appear on a cardholder's account before money has actually moved anywhere, why a pending charge can differ from the amount that eventually posts, and why traditional card programs operate with multi-day cashflow lags that this platform is specifically designed to collapse.

This page describes the lifecycle as it works across the card industry generally (Visa, Mastercard, and similar four-party networks), and then maps it onto the objects and statuses you'll encounter in the API.

Phase 1: Authorization

Authorization happens in real time (typically within 1–3 seconds) at the moment a cardholder attempts a purchase.

1. The cardholder presents their card (physically, or by entering card details online).
2. The merchant's terminal or payment gateway constructs an authorization request containing the card number, transaction amount, merchant details (including a Merchant Category Code, or MCC, which classifies the type of business), and various risk-related data points.
3. This request travels to the merchant's acquirer (or acquirer processor), which forwards it onto the relevant card network (Visa, Mastercard, etc.).
4. The network routes the request to the issuer (or, in practice, the issuer processor acting on the issuer's behalf) — the entity that holds the cardholder's account.
5. The issuer processor (on behalf of or in conjunction with the issuer) evaluates the request: e.g. is the card active, is there sufficient available balance, does the transaction pass fraud and risk checks, and does it fall within configured limits?
6. The issuer responds with an approval or decline, which travels back through the same chain to the merchant.

📘

This message exchange is standardized across the industry. Most card networks use message formats based on ISO 8583, a decades-old but still-dominant standard for financial transaction messaging. You won't interact with ISO 8583 directly through the API (the platform abstracts this into a REST/JSON interface), but you'll see its influence in field naming conventions and status codes across the industry.

The authorization hold

When a transaction is approved, the issuer places an authorization hold on the cardholder's account for the authorized amount. This hold reduces the funds available for further spending, but no money has actually moved between any of the parties yet — the hold is an accounting reservation, not a transfer.

This is why, by way of example, a hotel pre-authorization for $500 can appear on a cardholder's account immediately, even though the hotel won't actually be paid for several more days, and why that $500 hold might later be replaced by a different amount (e.g. $620 including incidentals) once the actual stay is billed.

Authorization holds typically expire automatically after a period (commonly 1–7 days, depending on the network and merchant category) if they're never converted into a cleared transaction.

Phase 2: Clearing

Clearing is the process by which authorized transactions are finalized and presented for payment. Rather than happening transaction-by-transaction in real time, clearing is typically batched:

1. At the end of a business day (or at some other interval), the merchant submits a batch of all its approved authorizations to its acquirer.
2. The acquirer forwards this batch to the card network.
3. The network sorts transactions by issuer and presents each issuer with the transactions clearing against its cardholders' accounts.
4. The issuer converts each matching authorization hold into a posted transaction; at this point, the transaction amount is finalized (and may differ somewhat from the original authorization, as in the hotel example above), and the cardholder's ledger reflects an actual debit rather than just a hold.

Clearing is also the point at which a transaction becomes eligible for interchange: the fee the issuer and other parties collect from the acquirer for each transaction (covered in depth in Interchange & Platform Economics).

Phase 3: Settlement

Settlement is the actual movement of funds between the parties, reconciling the obligations created during clearing:

1. The issuer pays the card network the net amount owed for transactions its cardholders made.
2. The network pays the acquirer (having deducted its own assessment fees).
3. The acquirer pays the merchant (having deducted its merchant discount rate, which includes interchange and the acquirer's own margin).

In a traditional card program, this chain of payments typically takes T+1 to T+5 business days from the clearing date, meaning there's a real lag between when a cardholder's funds are reserved (authorization) and when those funds actually move through the system to the merchant (settlement). This delay is a structural feature of how multi-party card networks operate, and it has significant cashflow implications for issuers and program managers, covered in Interchange & Platform Economics.

Phase 4: Disputes and chargebacks

Not every transaction completes cleanly. A cardholder may not recognize a charge, a merchant may fail to deliver goods or services, or a transaction may be fraudulent. The dispute process exists to resolve these situations:

1. The cardholder raises a dispute with their issuer, typically within a window defined by the card network's rules (often 60–120 days from the transaction or expected delivery date, and sometimes longer for specific dispute reasons).
2. The issuer reviews the dispute against the network's defined reason codes (each network maintains its own taxonomy, e.g. goods not received, fraudulent transaction, duplicate processing).
3. If the dispute appears valid, the issuer raises a chargeback reversing the transaction and returning the funds to the cardholder, while debiting the acquirer (who in turn typically debits the merchant).
4. The merchant (via the acquirer) may represent the chargeback, submitting evidence that the transaction was valid (e.g. proof of delivery, a signed receipt).
5. If the issuer rejects the representment, the case may proceed to arbitration, where the card network makes a binding decision.

stateDiagram-v2
    [*] --> Authorized: Issuer approves
    [*] --> Declined: Issuer declines
    Declined --> [*]
    Authorized --> Cleared: Merchant batch processed
    Cleared --> Settled: Funds move between parties
    Settled --> Disputed: Cardholder raises a dispute
    Disputed --> Chargeback: Issuer reverses the transaction
    Disputed --> Settled: Dispute resolved in merchant's favor
    Chargeback --> Representment: Merchant/acquirer contests
    Representment --> Settled: Chargeback upheld in merchant's favor
    Representment --> Chargeback: Chargeback stands
    Settled --> [*]
    Chargeback --> [*]

The full picture

sequenceDiagram
    participant CH as Cardholder
    participant M as Merchant
    participant AcqP as Acquirer / Acquirer Processor
    participant Net as Card Network
    participant Iss as Issuer / Issuer Processor

    Note over CH,Iss: AUTHORIZATION — real time (seconds)
    CH->>M: Presents card for payment
    M->>AcqP: Authorization request
    AcqP->>Net: Forward authorization request
    Net->>Iss: Route to issuer
    Iss->>Iss: Check balance, limits, fraud rules
    Iss->>Net: Approve / Decline
    Net->>AcqP: Forward response
    AcqP->>M: Approve / Decline
    M->>CH: Transaction approved
    Note over Iss: Authorization hold placed —<br/>no funds have moved yet

    Note over M,Iss: CLEARING — typically daily, batched
    M->>AcqP: Submit batch of approved transactions
    AcqP->>Net: Forward batch
    Net->>Iss: Present for clearing
    Iss->>Iss: Hold converted to posted transaction

    Note over Iss,M: SETTLEMENT — typically T+1 to T+5
    Iss->>Net: Settlement funds
    Net->>AcqP: Settlement funds (minus assessment)
    AcqP->>M: Settlement funds (minus MDR)

(There are other participants (e.g. program managers, sponsors, third party banks, token service providers, payment facilitators, and others), which have not been included in this explanation so as not to overcomplicate the matter.)

How this maps to the platform

The GET /cards/transactions endpoint returns a transStatus field with values 1 Pending, 2 Cleared, 3 Completion, 4 Declined, and 5 Error (see Pagination, Filtering & Rate Limits). Conceptually, these align with the lifecycle above:

🚧

This mapping is conceptual, based on the standard industry lifecycle and the field's enum values, but the transStatus doesn't follow the precise meaning or conditions that move a transaction between each stage. Treat this table as a starting mental model, and verify specific transitions against observed behavior.

T+0 settlement

The most significant divergence of the Axys platform from the traditional model described above is timing. In a traditional program, the delay between Phase 1 (authorization, real-time) and Phase 3 (settlement, T+1 to T+5) is a structural inevitability.

This platform model is built around T+0 settlement, collapsing this gap so that, from your Program's perspective, the funds position reflects same-day rather than waiting multiple days for the underlying network settlement cycle to complete. The cashflow and liquidity implications of this are covered in Interchange & Platform Economics.

Pending vs available balances

The ledgerBalance / availableBalance split on a Card's Account (see Accounts, Wallets & Deposit Addresses) follows the same general pending vs complete pattern described for digital asset deposits in Digital-Asset Rails & Custody. An amount can be reflected in one balance before it's reflected in the other, mirroring the authorization-hold-vs-posted distinction described above for traditional card transactions.

What's next

• Stakeholders in a Card Program
• Interchange & Platform Economics
• Transactions & Fees