Disputes

Overview

A dispute (also called a chargeback) happens when a customer asks their bank to reverse a card payment. The disputed amount is held from your balance until the dispute closes. You can challenge the dispute with evidence, or accept it.

Finding disputes

Disputes don't send webhooks, so check for them on a schedule. Check at least once a day, and more often for open disputes close to their deadline.

• list-disputes: Every dispute on your account, newest first. Page through the results with per_page, after, and before. The endpoint doesn't filter by status or date, so filter the results in your own code.
• list-disputes-by-payment: The disputes on one payment.
• find-dispute: One dispute by its dsp_ ID.

A payment with a dispute reports the status DISPUTED. See Payment lifecycle.

Each dispute includes:

• status: Where the dispute is. See Dispute statuses.
• amount and currency: The disputed amount.
• reason: Why the customer disputed the payment.
• suggested_evidence: The kinds of evidence most likely to help with this reason.
• deadline_at: When your response is due, if one is due.

Dispute statuses

If you don't respond to an OPEN or REOPENED dispute before deadline_at, it closes as LOST. If the bank doesn't answer a challenge in time, it closes as WON.

Challenging a dispute

Challenge a dispute when you can show the payment was valid, for example with a delivery receipt, signed contract, or usage record. The dispute's suggested_evidence lists what is most likely to help.

Evidence files must be PDF, PNG, JPG, or JPEG, and each must be smaller than 10 MB. You can add evidence only while a dispute is OPEN or REOPENED.

In the Merchant Dashboard

1. Under Transactions, open the disputed payment, then open its dispute.
2. In Response, choose Challenge.
3. Upload your evidence files.
4. Select Submit.

For a REOPENED dispute, follow the same steps to escalate it with more evidence.

Accepting a dispute

If you agree with the customer, or the evidence isn't worth gathering, choose Accept in the dispute's Response section in the dashboard. You can accept a dispute that is OPEN, CHALLENGED, or REOPENED. It closes as LOST right away.