> ## Documentation Index > Fetch the complete documentation index at: https://docs.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Overview > How card transactions are represented, retrieved, and tracked over their lifecycle. A card transaction represents one card use end-to-end: an in-store purchase, an online checkout, an ATM withdrawal, or a third-party push to the card. Reap captures every authorization, clearing, reversal, refund, and decline that the card network sends, and exposes the result as a single transaction resource that evolves over time. You do not poll the card network or reconcile authorizations against clearings yourself. Reap does that, and you read the current state through the API or react to it through webhooks. ## Anatomy of a transaction Every transaction carries the same envelope of identifying fields, plus a status-specific amount shape and a chronological event log. | Field | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The transaction ID. Stable across the full lifecycle. | | `accountId`, `cardId` | The account and card the transaction was made on. | | `status` | `PENDING`, `CLEARED`, `DECLINED`, or `VOID`. See [Lifecycle](/transactions/lifecycle). | | `channel` | How the transaction was initiated: `POS`, `ECOMMERCE`, `ATM`, or `VISA_DIRECT`. | | `digitalWallet` | `APPLE_PAY`, `GOOGLE_PAY`, `MERCHANT_TOKEN` (the merchant stored the card for a recurring or saved-card payment), or `null` if no digital wallet was used. | | `merchant` | Merchant name, city, country, MCC code, and MCC category. | | `currency` | The card's billing currency (ISO 4217). Fixed per card program (for example `USD` or `HKD`). | | `originalCurrency` | The currency the merchant charged in. Equal to `currency` for same-currency transactions, otherwise the merchant's local currency. | | `amount`, `originalAmount` | Amount charged to the cardholder (in `currency`) and amount the merchant charged (in `originalCurrency`). The shape of these fields varies by status. See [Amounts](/transactions/amounts). | | `conversionRate` | Effective rate Reap applied to convert `originalAmount` to `amount`. Present on `PENDING` and `CLEARED`; absent on `VOID` and `DECLINED`. | | `events` | Chronological log of every lifecycle event (authorization, clearing, reversal, refund, decline). Oldest first. | | `declineReason` | Present only on `DECLINED` transactions. See [Decline reasons](/transactions/decline-reasons). | | `occurredAt` | When the underlying card activity happened. | | `createdAt`, `updatedAt` | When Reap first recorded the transaction and last modified it. | The response shape is a discriminated union on `status`. `DECLINED` transactions carry a `declineReason` and a flat `originalAmount`. `PENDING`, `CLEARED`, and `VOID` carry breakdowns instead, because their amounts can move as reversals, clearings, or refunds arrive. See [Amounts](/transactions/amounts) for the per-status field shapes and [Lifecycle](/transactions/lifecycle) for how they change. ## Retrieving transactions There are two endpoints, used for different jobs. ### List activities Use [List activities](/api-reference/activities/list-activities) to fetch a user's card history. This is the primary way to read transactions, because card transactions are part of a unified activity feed that also contains crypto deposits and (in Program-Funded programs) virtual asset postings. The feed is chronologically ordered and paginated, which matches what most product surfaces (transaction history screens, statements, exports) actually need. To scope the feed to card transactions: * `type=CARD_TRANSACTION` returns only card transactions. * `accountId=` scopes to one account (typically a user). * `cardId=` scopes to a specific card. * `cardTransactionStatus=PENDING,CLEARED` filters by status (comma-separated). Each item in the response carries the full card transaction object under `data`, identical to what `Get a card transaction by ID` returns. ### Get a card transaction by ID Use [Get a card transaction by ID](/api-reference/card-transactions/get-card-transaction) when you already have a transaction ID and want its current state. Common cases: rendering a transaction detail screen or refreshing a single row in your UI. The response schema is identical to items returned by the activities endpoint. ## Reacting to changes Subscribe to webhooks instead of polling. | Event | When it fires | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [`CARD_TRANSACTION_CREATED`](/api-reference/card-transaction-created) | A new transaction is recorded for the first time (a new authorization, a decline, or a standalone refund). | | [`CARD_TRANSACTION_UPDATED`](/api-reference/card-transaction-updated) | An existing transaction receives a new lifecycle event (clearing, reversal, refund, or a previously pending transaction transitioning to declined). | Both events carry the full transaction object. The `events` array on the payload always reflects the complete history at the time of delivery, ordered oldest first, so you do not need to stitch events together across deliveries. To know which event triggered a given webhook, read `triggerEventId` on the payload and resolve it against `events` for the exact event type and amounts that drove the change. Do not assume it is the last entry in `events` (webhooks might arrive out of order if your endpoint is unreachable); use `triggerEventId` as the authoritative pointer. Use the event `id` for idempotency. See [Webhooks](/webhooks/overview) for delivery, retries, and signature verification. ## Next The four statuses and the scenarios that drive them. Per-status amount fields, currency, and conversion rate. Every code that can appear on a declined transaction.