Skip to main content
When a cardholder does not recognise a charge, never received what they paid for, or was billed the wrong amount, you file a dispute and Reap takes the case to the card network. You send the transaction ID and a reason; Reap derives the card, the cardholder identity, and the currency from the transaction itself. Subscribe to CARD_DISPUTE_STATUS_UPDATED for the outcome. Cases can take weeks to resolve, so treat the webhook as the source of truth rather than polling.
A dispute is not a fraud alert. Confirming a fraud alert blocks the card but does not recover the money. A dispute is the path for recovering the money. The two are independent: neither requires the other, and you can file both against the same transaction.

​
Before you file

An Idempotency-Key is required on File dispute. A retry carrying the same key replays the original response, so a network timeout on your side does not turn into an error on the retry. Without it a retry of a request that already succeeded returns CARD_DISPUTE_ALREADY_EXISTS.

​
File a dispute

1

Collect the reason from the cardholder

Pick the dispute reason that matches what the cardholder is telling you. The reason drives how the network handles the case, so it is worth surfacing as a clear choice in your UI rather than guessing.
2

File it

Call File dispute with transactionId and reason.Optionally send amount to dispute part of the charge, and contactEmail to route the outcome somewhere other than the cardholder’s email on file. Everything else is derived from the transaction. The case is created as RECEIVED and Reap takes it from there.
3

Track the outcome

You receive CARD_DISPUTE_STATUS_UPDATED on every status change through to resolution.

​
Dispute lifecycle

DECLINED and LOST are easy to confuse. DECLINED means the case never reached the card network. LOST means it was filed and the network ruled for the merchant. A dispute can be canceled or declined at any point before resolution. resolvedAt is set once the case reaches a final status.

​
How a refund is calculated

File the cardholder amount: the charge plus FX markup and ATM fees. Omit amount to dispute the full cleared total. The cardholder is credited refundedAmount when the case reaches REFUNDED, not the disputed amount. refundedAmount stays null until then. Read it from the dispute resource or from CARD_DISPUTE_STATUS_UPDATED. The same credit is appended to the disputed transaction as a DISPUTE_REFUND event and delivered in CARD_TRANSACTION_UPDATED. The transaction’s amount.refunded and amount.current reflect it. The credit includes a proportional share of FX markup and ATM variable fee. The per-withdrawal ATM fee stays charged, the same way a merchant refund leaves it charged. Take a 105ATMwithdrawal:105 ATM withdrawal: 100 purchase, 1FX,1 FX, 1 ATM variable, $3 per-withdrawal fee.
  • A full dispute files 105.Afullrefundcredits105. A full refund credits 102. The $3 stays charged.
  • A half dispute files 52.50.Amatchingrefundcredits52.50. A matching refund credits 51.
If you keep the cardholder’s balance, as in External authorization, apply the credit from the DISPUTE_REFUND event on the transaction, the same way you apply a merchant REFUND. Do not also credit from the dispute webhook, or the refund is booked twice. See Keeping your ledger in sync.

​
Next

Dispute Reasons

The full reason vocabulary, grouped by category.