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.
Scenarios
The scenarios below cover almost every transaction you will see. Each describes how the status, theevents array, and the amount fields change, and which webhook fires.
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 inPENDING with one AUTHORIZATION event, then transitions to CLEARED when a CLEARING event arrives.
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 inDECLINED. 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.
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 pending amount is released back to the account and the status becomesVOID. 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 staysPENDING, 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.
Refund on a cleared transaction
The merchant refunds a transaction that has already cleared. The transaction staysCLEARED; 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.
You receive a CARD_TRANSACTION_UPDATED webhook with the full transaction object, including the new refund event.
Standalone refund (no original transaction)
Sometimes a merchant sends a refund that does not correspond to any existing transaction on Reap. The most common cause is a long delay between the original purchase and the refund. In this case Reap creates a brand new transaction inCLEARED 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 inVOID 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 staysPENDING, 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.
Clearing for more than the authorized amount
The cleared amount can also exceed the authorized amount without any incremental authorization beforehand. The most common cause is tips at restaurants in tip-prompt jurisdictions: the merchant authorizes the bill, the cardholder writes in a tip on the receipt, and the merchant clears for bill plus tip. The difference is usually small. The transaction still transitions normally fromPENDING to CLEARED, and amount.cleared reflects what was actually charged. If you want to see exactly what changed, the events array carries the precise authorization and clearing amounts in order.
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.