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. To scope the feed to card transactions:

• type=CARD_TRANSACTION returns only card transactions.
• accountId=<id> scopes to one account (typically a user).
• cardId=<id> 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 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 (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 for delivery, retries, and signature verification.

​

Next