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 creditedrefundedAmount 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.
Next steps
File a Dispute
Check the requirements, file the dispute, and track it to resolution.
FAQ
Short answers to common integration questions.