> ## 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. # Lifecycle > The four transaction statuses and the scenarios that drive them. 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 | Status | Meaning | | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | | `PENDING` | The authorization was approved and funds are reserved on the account. The transaction has not yet been settled by the merchant. | | `CLEARED` | The merchant has collected and the cardholder has been charged. | | `VOID` | The authorization was fully reversed before clearing. No funds were charged. Also used for zero-amount card validity checks. | | `DECLINED` | The authorization was rejected. No funds were reserved or charged. | `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](#refund-on-a-cleared-transaction-related-refund). ```mermaid theme={null} stateDiagram-v2 [*] --> PENDING: authorization approved [*] --> DECLINED: authorization rejected [*] --> VOID: zero-amount verification [*] --> CLEARED: standalone refund [*] --> CLEARED: offline / direct clearing PENDING --> CLEARED: merchant settles PENDING --> VOID: full reversal (incl. auto-reversal) CLEARED --> CLEARED: additional clearing / refund ``` ## 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](/transactions/amounts). In User-Funded and Managed projects this is the balance Reap authorizes against. In [External-authorization](/transactions/external-authorization/overview) 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. ```mermaid theme={null} sequenceDiagram participant Network as Card network participant Reap participant Backend as Your backend Network->>Reap: Authorization request Reap-->>Network: Approved Reap->>Backend: CARD_TRANSACTION_CREATED (status: PENDING) Note over Network,Backend: Hours to several days later Network->>Reap: Clearing Reap->>Backend: CARD_TRANSACTION_UPDATED (status: CLEARED) ``` 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. ```mermaid theme={null} sequenceDiagram participant Network as Card network participant Reap participant Backend as Your backend Network->>Reap: Clearing (no prior authorization) Reap->>Backend: CARD_TRANSACTION_CREATED (status: CLEARED) ``` 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](/transactions/decline-reasons) for the full code list. No further events follow. You receive one `CARD_TRANSACTION_CREATED` webhook with `status: DECLINED`. Not every declined attempt becomes a transaction in Reap. When the merchant or the card network rejects the attempt before it reaches Reap (for example, an obvious fraud signal at the terminal), no record is created. A `DECLINED` status in Reap always means Reap declined it, which is why `declineReason` is always populated. ### 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. ```mermaid theme={null} sequenceDiagram participant Network as Card network participant Reap participant Backend as Your backend Network->>Reap: Authorization ($200) Reap->>Backend: CARD_TRANSACTION_CREATED (PENDING) Network->>Reap: Reversal ($200) Reap->>Backend: CARD_TRANSACTION_UPDATED (VOID) ``` 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. ```mermaid theme={null} sequenceDiagram participant Network as Card network participant Reap participant Backend as Your backend Network->>Reap: Authorization + Clearing Reap->>Backend: CARD_TRANSACTION_UPDATED (CLEARED) Note over Network,Backend: Days later Network->>Reap: Refund Reap->>Backend: CARD_TRANSACTION_UPDATED (CLEARED, + REFUND event) ``` 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](#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](/cards/3d-secure). ## Testing the lifecycle The sandbox lets you drive each scenario end-to-end without a real card network. See [Testing in Sandbox](/transactions/testing-in-sandbox) for the simulation endpoints that produce authorizations, clearings, reversals, refunds, and declines.