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. |
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. Always USD. |
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. |
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. |
occurredAt | When the underlying card activity happened. |
createdAt, updatedAt | When Reap first recorded the transaction and last modified it. |
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 for the per-status field shapes and Lifecycle for how they change.
Retrieving transactions
There are two endpoints, used for different jobs.List activities
Use 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_TRANSACTIONreturns only card transactions.accountId=<id>scopes to one account (typically a user).cardId=<id>scopes to a specific card.cardTransactionStatus=PENDING,CLEAREDfilters by status (comma-separated).
data, identical to what Get a card transaction by ID returns.
Get a card transaction by ID
Use Get a card transaction by ID 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 | A new transaction is recorded for the first time (a new authorization, a decline, or a standalone refund). |
CARD_TRANSACTION_UPDATED | An existing transaction receives a new lifecycle event (clearing, reversal, refund, or a previously pending transaction transitioning to declined). |
events array on the payload always reflects the complete history at the time of delivery, so you do not need to stitch events together across deliveries.
Use the event id for idempotency. See Webhooks for delivery, retries, and signature verification.
Next
Lifecycle
The four statuses and the scenarios that drive them.
Amounts
Per-status amount fields, currency, and conversion rate.
Decline reasons
Every code that can appear on a declined transaction.