Skip to main content
This page files one dispute end to end. You start with a cleared transaction and the reason the cardholder gives you, and finish with a dispute that Reap takes to the card network and reports on until it is resolved.

Before you start

  • The transaction has status CLEARED, which means the money has moved. PENDING and VOID transactions 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 CANCELED or DECLINED, 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
File within 75 days of clearing where you can. Reap files a later dispute on a best-effort basis, and the card network may still refuse it.
Every request takes an 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 with GET /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.