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 determines whether a signature is needed and 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.
3

Check whether a signature is needed

The response carries requiresCardholderSignature. When it is true the dispute is created as PENDING_SIGNATURE and will not progress until the cardholder signs. Continue to Collect the cardholder signature.When it is false the dispute is created as RECEIVED and Reap takes it from there.
4

Track the outcome

You receive CARD_DISPUTE_STATUS_UPDATED on every status change through to resolution.

​
Collect the cardholder signature

Fraud and consumer disputes need a signed statement from the cardholder before the case can move. Reap generates a pre-filled form and gives you a link to hand to them.
1

Mint a link

Call Mint signature link. You get back a url and an expiresAt one hour out.
2

Send the cardholder to it

Open the url in a browser or web view. The form is pre-filled with the dispute details; the cardholder reviews and signs.
3

Mint a fresh link if it expires

Links are single-use instances with a one-hour life and are never cached. Call the endpoint again for a new one. Concurrent links are safe, and each stays valid until it expires or is signed.
Signing does not update the dispute instantly. Reap confirms the signed form separately, so reading the dispute right after the cardholder finishes can still return PENDING_SIGNATURE. That is expected. Wait for CARD_DISPUTE_STATUS_UPDATED to move to RECEIVED, and do not send the cardholder back to sign a second time.
Requesting a link for a dispute that does not need one returns CARD_DISPUTE_SIGNATURE_NOT_REQUIRED.

​
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 also be sent back to PENDING_SIGNATURE after review if more is needed from the cardholder, and can be canceled or declined at any point before resolution. resolvedAt is set once the case reaches a final status.

​
Next

Dispute Reasons

The full reason vocabulary, grouped by category, and which ones need a cardholder signature.