Lifecycle

A card transaction is created the first time the card network sends Reap an event for it, and evolves as more events arrive. The transaction id is stable for the entire life of the transaction. The status and the events array are what change.

​

Statuses

CLEARED is terminal in the sense that the transaction stays CLEARED even when refunds arrive later. Refunds append a new event and adjust the amount fields, but never move the status. See Refund on a cleared transaction.

​

Balances during a transaction

Card spend moves an account’s balance in two phases, mirroring the network:

• Authorization places a hold. The authorized amount is reserved and the account’s available balance drops immediately, but nothing has settled yet. Holds are provisional and are released by a reversal or replaced by a real charge at clearing.
• Clearing converts the hold into a settled charge. A reversal releases the hold instead; a refund credits the account after clearing.

The events array is the audit trail of these movements. The transaction’s amount breakdown tracks authorized vs reversed while PENDING and cleared vs refunded once CLEARED, with amount.current always carrying the net effect - see Amounts. In User-Funded and Managed projects this is the balance Reap authorizes against. In External-authorization projects Reap forwards the decision to you, and you track these same movements in your own ledger.

​

Scenarios

The scenarios below cover almost every transaction you will see. Each describes how the status, the events array, and the amount fields change, which webhook fires, and the balance effect.

​

Authorization and clearing

The default path. The cardholder presents the card, the merchant requests an authorization, Reap approves it, and one to several days later the merchant submits the charge for settlement. The transaction is created in PENDING with one AUTHORIZATION event, then transitions to CLEARED when a CLEARING event arrives. The hold placed at authorization becomes a settled charge at clearing.

​

Clearing amount vs. authorized amount

The cleared amount frequently differs from what was authorized. The transaction still moves PENDING → CLEARED; only the amounts and the residual hold differ.

• Equal. The merchant clears exactly the authorized amount. amount.cleared equals amount.authorized; the hold converts to a charge with no remainder.
• Less than authorized (partial clearing). The merchant clears less, and the unused portion of the hold is released immediately. Classic case: a hotel authorizes the room rate plus an incidentals buffer, then clears only the room rate at check-out. Auth $200 → clearing $150 → status CLEARED, amount.cleared $150, and the remaining $50 returns to the account.
• More than authorized (over-clearing). The merchant clears more than authorized with no incremental authorization beforehand - common with tips (restaurants) and automated fuel dispensers. Auth $200 → clearing $220 → amount.cleared $220; the extra $20 is charged on top of the released hold.
• Additional clearings. A single authorization can receive more than one clearing (multi-leg travel, split shipments). Each appends a CLEARING event and adds to amount.cleared while the status stays CLEARED.

​

Offline and direct clearing

Some transactions clear without Reap ever seeing an authorization. Offline-capable terminals - transit gates, in-flight purchases - accept the card without a real-time authorization and submit the charge later. Reap creates the transaction directly in CLEARED with a single CLEARING event and the full amount as debt. There is no hold to release, because none was ever placed. You receive a CARD_TRANSACTION_CREATED webhook (not UPDATED) with status: CLEARED and a single CLEARING event.

​

Decline at authorization

The card network requests an authorization that Reap rejects (insufficient funds, frozen card, blocked merchant category, and so on). No funds are held and the transaction is created directly in DECLINED. The declineReason field on the response tells you why; see Decline reasons for the full code list. No further events follow. You receive one CARD_TRANSACTION_CREATED webhook with status: DECLINED.

​

Full reversal

The merchant cancels the authorization before settling. The entire hold is released back to the account and the status becomes VOID. The classic example is a hotel or rental-car pre-authorization released at check-out once the final amount is known. You receive one CARD_TRANSACTION_UPDATED webhook with status: VOID and a new REVERSAL event appended to events.

​

Partial reversal

The merchant releases part of the authorized amount without settling yet. The transaction stays PENDING, but the amount.reversed field grows and amount.current drops to reflect the remaining hold. A common pattern: a hotel pre-authorizes the nightly rate plus an incidentals hold at check-in, releases the unused incidentals at check-out, then clears for just the actual charges. You see one AUTHORIZATION, then a REVERSAL, then a CLEARING, and the status moves PENDING → PENDING → CLEARED. You receive CARD_TRANSACTION_UPDATED for each reversal.

​

Automatic reversal

If a PENDING authorization is never cleared or reversed by the merchant, the card network eventually releases it and Reap processes that like any other reversal: a REVERSAL event is appended, the hold is released, and the status becomes VOID. Stale holds are released by the network after set amount of days. You receive one CARD_TRANSACTION_UPDATED webhook with status: VOID.

​

Refund on a cleared transaction (related refund)

The merchant refunds a transaction that has already cleared. The transaction stays CLEARED; a REFUND event is appended to events, amount.refunded grows, and amount.current drops by the refunded amount. A full refund leaves amount.current at 0 while the status remains CLEARED. The refunded amount is credited back to the account. You receive a CARD_TRANSACTION_UPDATED webhook with the full transaction object, including the new refund event.

​

Standalone refund (unrelated refund)

Sometimes a merchant sends a refund that does not correspond to any existing transaction on Reap - a tax refund on an overseas purchase, a goodwill credit, or a return long after the original purchase. Reap creates a brand new transaction in CLEARED with a single REFUND event and no preceding authorization or clearing. You receive a CARD_TRANSACTION_CREATED webhook (not UPDATED) with status: CLEARED and a single event of type REFUND. From your side, this transaction is treated like any other cleared transaction in the activity feed.

​

Other cases worth knowing

​

Zero-amount verifications

Some merchants run a zero-amount authorization to check the card is valid without charging it (typical for subscription sign-ups and saved-card flows). Reap records this as a transaction created directly in VOID with a single AUTHORIZATION event of amount 0. No funds are reserved and no further events arrive.

​

Incremental authorizations

A merchant can raise the authorized amount on a transaction without cancelling the original auth. Restaurants adding a tip and hotels topping up an open pre-authorization both do this. The transaction stays PENDING, a second AUTHORIZATION event is appended, and amount.authorized grows by the incremental amount. The eventual clearing may match the total authorized amount or differ from it - see Clearing amount vs. authorized amount.

​

3D Secure on ECOMMERCE authorizations

Online (channel: ECOMMERCE) authorizations may include a 3D Secure step in which the issuer must confirm the cardholder before the authorization can proceed. Reap handles 3DS for you and exposes a per-card setting that controls how challenges are resolved - SMS OTP by default, or an in-app flow you drive from your backend. See 3D Secure.

​

Testing the lifecycle

The sandbox lets you drive each scenario end-to-end without a real card network. See Testing in Sandbox for the simulation endpoints that produce authorizations, clearings, reversals, refunds, and declines.