Transaction Lifecycle & Ledgers

A transaction is a financial event that may move funds. Every transaction has a type (CARD, PAYMENT, EXTERNAL_PAYMENT, INTERNAL_TRANSFER, MANAGEMENT_OPERATION, FEE, INTEREST, DISPUTE, REWARD), one status from a single status set, an events[] lifecycle log, and transfer_ids[] — the immutable movements of funds it holds. Read the transfers with GET /v1/transactions/{transaction_id}/transfers and the book transfers they posted with …/book-transfers. Transfers never change; a reversal is a new transaction.

Non-card types use the movement events CREATED, SETTLED, DECLINED, RETURNED, REVERSED, RELEASED, CANCELED — see Moving money. The rest of this page is the CARD type: a timeline of card-network events.

Card transactions

A CARD transaction is a timeline of network events. status is the lifecycle of the whole object; events[] is the log. Discriminate each event on type.

Status (`CARD`)

Status	Meaning
`PENDING`	An approved authorization is holding funds. No clearing yet.
`SETTLED`	A `CLEARING` or approved `FINANCIAL_AUTHORIZATION` posted. Returns keep this status.
`VOIDED`	A `VOID` released the pending hold.
`EXPIRED`	The auth window closed (`AUTHORIZATION_EXPIRY`) without a clearing.
`DECLINED`	The first authorization (or financial authorization) was not approved.

result is APPROVED or DECLINED. On a decline, decline_reason names the cause (INSUFFICIENT_FUNDS, CARD_PAUSED, AUTHORIZATION_RULE, and the rest of the closed set). Approved transactions set decline_reason to null.

Card-network events

events is chronological. Every item has amount (integer minor units), result, rule_results[], and created_at. Discriminate on type:

`type`	Effect on status
`AUTHORIZATION`	Dual-message auth. Approved → `PENDING`. Declined → `DECLINED`.
`AUTHORIZATION_ADVICE`	Adjusts the pending hold. Status stays `PENDING`.
`FINANCIAL_AUTHORIZATION`	Single-message auth. Approved → `SETTLED`. Declined → `DECLINED`.
`CLEARING`	Captures a pending auth. Status → `SETTLED`.
`VOID`	Merchant reversal of a pending auth. Status → `VOIDED`.
`AUTHORIZATION_EXPIRY`	Auth window closed. Status → `EXPIRED`.
`RETURN`	Refund against a settled purchase. Status stays `SETTLED`.
`RETURN_REVERSAL`	Undoes a `RETURN`. Status stays `SETTLED`.

rule_results lists authorization-control rules evaluated for that event (ALLOW, DECLINE, CHALLENGE, or NO_MATCH). Rules run only on AUTHORIZATION and FINANCIAL_AUTHORIZATION events, so those two carry one entry per evaluated rule; AUTHORIZATION_ADVICE, CLEARING, VOID, AUTHORIZATION_EXPIRY, RETURN, and RETURN_REVERSAL always send an empty array.

State diagram (`CARD`)

stateDiagram-v2
  [*] --> PENDING: AUTHORIZATION approved
  [*] --> DECLINED: AUTHORIZATION or FINANCIAL_AUTHORIZATION declined
  [*] --> SETTLED: FINANCIAL_AUTHORIZATION approved
  PENDING --> PENDING: AUTHORIZATION_ADVICE
  PENDING --> SETTLED: CLEARING
  PENDING --> VOIDED: VOID
  PENDING --> EXPIRED: AUTHORIZATION_EXPIRY
  SETTLED --> SETTLED: RETURN / RETURN_REVERSAL

                    ┌─────────────────────────────────┐
  AUTHORIZATION     │                                 │
  approved ────────►│            PENDING              │
                    │                                 │
                    └───┬──────────┬──────────┬───────┘
                        │          │          │
         AUTHORIZATION_ │          │          │
         ADVICE (stay)  │          │          │
                        │          │          │
                      VOID    EXPIRY      CLEARING
                        │          │          │
                        v          v          v
                     VOIDED     EXPIRED    SETTLED ◄── FINANCIAL_AUTHORIZATION
                                                 │         approved
                                                 │
                                      RETURN / RETURN_REVERSAL
                                                 │
                                                 v
                                              SETTLED

Declined authorizations never enter PENDING.

Amounts (`CARD`)

amounts splits five views of the same purchase:

authorization: hold created by an approved auth. Null when the transaction never authorized.
settled: posted amount after clearing or financial authorization. Null until the transaction is SETTLED.
cardholder: billed amount in the cardholder’s currency (Money).
cardholder_conversion_rate: FX rate from merchant currency as a decimal string, never a float. "1.000000" means merchant and cardholder currencies match.
merchant: amount requested in merchant currency.

All money fields use integer minor units (4280 + USD is $42.80). cardholder_conversion_rate is a decimal string.

Card-only lifecycle operations

These operations apply to CARD transactions; other types return 422.

Expire: POST /v1/transactions/{transaction_id}/expire-authorization on a PENDING transaction. Appends AUTHORIZATION_EXPIRY and sets status EXPIRED. Send Idempotency-Key.
Route: POST /v1/transactions/{transaction_id}/route with financial_account_id on a SETTLED transaction. Moves the posting onto another financial account on the same issuing wallet. Send Idempotency-Key.
Fraud report: PUT /v1/transactions/{transaction_id}/fraud-report replaces the report (SUSPECTED_FRAUD, FRAUDULENT, or NOT_FRAUDULENT, plus fraud_type and comment). GET the same path to read it.
Enhanced commercial data: GET /v1/transactions/{transaction_id}/enhanced-commercial-data lists L2/L3 payloads (line items, tax, VAT, invoice). GET /v1/enhanced-commercial-data/{enhanced_commercial_data_id} returns one record by its id.

GET /v1/transactions lists transactions of every type (filter with type); GET /v1/transactions/{transaction_id} returns any one. Nested GET /v1/cards/{card_id}/transactions returns the CARD transactions of one card.