Overview

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. 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 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. type controls which kinds of activity the feed returns. It is the only parameter that does, so pass type=CARD_TRANSACTION whenever you want card transactions alone. It accepts several types, so type=CRYPTO_DEPOSIT,CARD_TRANSACTION returns deposits and transactions in one ordered, paginated feed. Every other filter narrows within its own kind and leaves the others untouched:

• accountId=<id> scopes to one account (typically a user).
• cardId=<id> restricts which card transactions come back, to a specific card.
• cardTransactionStatus=PENDING,CLEARED restricts which card transactions come back, by status (comma-separated).

So cardId=<id> on its own still returns that account’s crypto deposits alongside the card’s transactions. Combine it with type=CARD_TRANSACTION to get the card’s transactions by themselves. 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 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. 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; use triggerEventId as the authoritative pointer. Deliveries are not ordered, so upsert on data.id rather than expecting the create to arrive first, and ignore a payload whose updatedAt is older than what you have stored. Use the event id for idempotency. See Webhooks for delivery guarantees, retries, and signature verification.

​

Next