Skip to main content
Every dispute reports a status. This page maps each value to the action it calls for and explains what the cardholder is credited when a dispute reaches REFUNDED.

Statuses

A dispute can be canceled from RECEIVED, REVIEWING, or SUBMITTED, and declined from RECEIVED or REVIEWING. resolvedAt is set when the dispute is resolved, which is any of WON, LOST, REFUNDED, DECLINED, or CANCELED. WON is resolved even though REFUNDED follows it, so a set resolvedAt does not mean the last status change has arrived. DECLINED and LOST are often confused. DECLINED means the dispute never reached the card network. LOST means it was filed and the card network ruled for the merchant.

How a refund is calculated

The cardholder is credited refundedAmount when the dispute reaches REFUNDED, not the disputed amount. The disputed amount is the cardholder amount, which is the charge plus FX markup and ATM fees. Omit amount on POST /disputes to dispute the full cleared total, as File a Dispute describes. 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 amount.refunded and amount.current values on the transaction reflect it. The credit includes a proportional share of the FX markup and the ATM variable fee. The per-withdrawal ATM fee stays charged, the same way a merchant refund leaves it charged. Consider a USD 105 ATM withdrawal made up of a USD 100 purchase, USD 1 FX markup, USD 1 ATM variable fee, and a USD 3 per-withdrawal fee.
  • A full dispute files USD 105. A full refund credits USD 102, and the USD 3 stays charged
  • A half dispute files USD 52.50. A matching refund credits USD 51

Read the credit

Once the cardholder is credited, GET /disputes/:id returns the dispute with status set to REFUNDED, and CARD_DISPUTE_STATUS_UPDATED delivers the same resource in data when the status changes. For the full dispute of that withdrawal, refundedAmount holds USD 102 against the USD 105 filed, because the USD 3 per-withdrawal fee stays charged, and resolvedAt is set because the dispute is resolved. The reference page shows the full response.
If you keep the cardholder balance yourself, as you do under 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. Keeping your ledger in sync covers the full sequence.

Next steps

File a Dispute

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

FAQ

Short answers to common integration questions.