Skip to main content
Disputes let you challenge a cleared card transaction for a cardholder and have Reap take the dispute to the card network. When a cardholder does not recognize a charge, never received what they paid for, or was billed the wrong amount, you file a dispute with the transaction ID and a reason. Reap derives the card, the cardholder identity, and the currency from the transaction itself, files the dispute with the card network, and reports every status change until the dispute is resolved.

What Reap handles

You do not need to build any of the following.
  • Lookup of the card, the cardholder identity, and the currency, all derived from the transaction
  • The review of the dispute and the filing with the card network
  • The credit to the cardholder when the dispute reaches REFUNDED, recorded on the disputed transaction as a DISPUTE_REFUND event
  • CARD_DISPUTE_STATUS_UPDATED on every status change through to resolution

What you build

  • A clear reason choice in your UI, so you do not guess what the cardholder is telling you
  • The call to POST /disputes with the transaction ID and the reason
  • A handler for CARD_DISPUTE_STATUS_UPDATED that follows the dispute through to resolution
  • The credit on your own ledger from the DISPUTE_REFUND event, only when you keep the cardholder balance yourself

How it works

  • The cardholder tells you what went wrong with the charge
  • You pick the matching reason and file the dispute
  • Reap reviews the dispute, files it with the card network, and reports each status change
  • The card network rules for the cardholder or for the merchant
A dispute can take weeks to resolve, so treat the webhook as the source of truth rather than polling. Lifecycle and Statuses covers every status value and what each one calls for.

Core resources

One resource and one webhook, plus a transaction event, carry the whole flow.
  • A dispute records one challenge against one cleared transaction. POST /disputes creates it with status set to RECEIVED, and GET /disputes/:id reads it back. It carries reason, category, amount, refundedAmount, cardholder, and resolvedAt. GET /disputes returns your disputes and accepts category as a filter
  • CARD_DISPUTE_STATUS_UPDATED reports every status change through to resolution
  • The DISPUTE_REFUND event on the disputed transaction carries the credit and arrives in CARD_TRANSACTION_UPDATED

Use cases

Unrecognized charge

The cardholder did not authorize the charge. A counterfeit or stolen card was used in person, or the card details were used online, by phone, or by mail.

Charge taken without authorization

The merchant charged the card while it was blocked, after the authorization was declined, or without any authorization.

Wrong amount or duplicate charge

The charge was processed for the wrong amount, in the wrong currency, against the wrong card, or more than once.

Goods or services not received

The cardholder paid but never received the goods, received goods not as described, or was charged after canceling.

Disputes and fraud alerts

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.

Next steps

File a Dispute

Check the requirements, file the dispute, and track it to resolution.

Dispute Reasons

Every reason by category, and how to pick the closest match.
Lifecycle and Statuses covers every status value and how the refund is calculated. The FAQ answers the questions that come up most during an integration.