Before you start
- The transaction has status
CLEARED, which means the money has moved.PENDINGandVOIDtransactions cannot be disputed, and neither can a standalone refund, which pays the cardholder rather than charging them. The transaction lifecycle covers each status - The transaction first cleared within the last 120 days. The filing window is the same for every reason
- The amount you dispute is at most the cleared cardholder amount, net of refunds. The cardholder amount is the charge plus FX markup and ATM fees. When you omit
amount, the full cleared cardholder amount is disputed. A partly refunded transaction can still be disputed for the remainder - No live dispute exists on the transaction. You can file again only when the earlier dispute reached
CANCELEDorDECLINED, which means it never reached the card network - A reason that matches what the cardholder is telling you. Dispute Reasons lists every value by category
Authorization header with your API key as a bearer token and a Reap-Version header.
File and track the 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 card network handles the dispute, so show it as a clear choice in your UI rather than guessing.
2
File the dispute
Call
POST /disputes with transactionId and reason. Everything else is derived from the transaction, including the card, the cardholder identity, and the currency. An Idempotency-Key is required. A retry with 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.The dispute is created as RECEIVED and Reap handles it from that point. Keep the dispute id. In the response, amount is the full cleared cardholder amount when the request omits it, category is derived from the reason, and the cardholder block carries the identity Reap derived from the transaction. refundedAmount and resolvedAt stay null while the dispute is open. The POST /disputes reference shows the full request and response.Send amount as a number in the billing currency to dispute part of the charge. Send contactEmail to route the outcome somewhere other than the cardholder email on file. The response echoes it in cardholder.contactEmail.3
Track the outcome
Subscribe to
CARD_DISPUTE_STATUS_UPDATED. You receive it on every status change through to resolution, and data carries the dispute in the same shape as the POST /disputes response. The event reference shows the full payload.Return any 2xx status to acknowledge the event, and use the event id to skip a delivery you have already processed. A dispute can take weeks to resolve, so treat the webhook as the source of truth rather than polling. GET /disputes/:id returns the current dispute whenever you need it, and Lifecycle and Statuses maps each status to the action it calls for.List disputes
List the disputes in your project withGET /disputes, newest first. The reference page shows the request and the response. Filter by status, reason, category, cardId, or transactionId, or by the time the dispute was filed with filedFrom and filedTo.
Follow nextCursor when it holds a value. A null cursor means the last page.
Errors
Next steps
Dispute Reasons
Every reason by category, and how to pick the closest match.
Lifecycle and Statuses
Every status value, what to do about it, and how the refund is calculated.