ROOKDocs
Sign In
Transactions Guide

Transaction lifecycle

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)

StatusMeaning
PENDINGAn approved authorization is holding funds. No clearing yet.
SETTLEDA CLEARING or approved FINANCIAL_AUTHORIZATION posted. Returns keep this status.
VOIDEDA VOID released the pending hold.
EXPIREDThe auth window closed (AUTHORIZATION_EXPIRY) without a clearing.
DECLINEDThe 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:

typeEffect on status
AUTHORIZATIONDual-message auth. Approved → PENDING. Declined → DECLINED.
AUTHORIZATION_ADVICEAdjusts the pending hold. Status stays PENDING.
FINANCIAL_AUTHORIZATIONSingle-message auth. Approved → SETTLED. Declined → DECLINED.
CLEARINGCaptures a pending auth. Status → SETTLED.
VOIDMerchant reversal of a pending auth. Status → VOIDED.
AUTHORIZATION_EXPIRYAuth window closed. Status → EXPIRED.
RETURNRefund against a settled purchase. Status stays SETTLED.
RETURN_REVERSALUndoes 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)

mermaid 
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
Code 
                    ┌─────────────────────────────────┐
  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.