Disputes

​

What Is a Dispute?

A dispute (also called a chargeback) occurs when a customer contacts their bank or card network to reverse a payment they made to you. The network then notifies us, and we create a dispute record against the original charge. Disputes are initiated entirely by the customer and their bank. You cannot prevent one from being opened. What you can control is whether you respond with evidence, and the quality of that evidence determines whether the dispute is resolved in your favour or against you.

---

​

Financial Impact

Understanding what happens to your money at each stage is critical.

​

When a dispute is created

The disputed amount is put under review, and nothing happens to it while the dispute stays under review. A flat dispute fee, however, is deducted from your balance at this point, as soon as the dispute record is created, regardless of how it is later resolved.

​

When you win (won)

The dispute was resolved in your favour. The disputed funds remain in your account and the reversal does not proceed. The dispute fee already charged when the dispute was created is not refunded.

​

When you lose (lost)

The dispute was resolved against you. The disputed amount is returned to the customer and deducted from your balance at this point. The dispute fee is not charged again here, since it was already deducted when the dispute was created.

​

When a dispute is closed (closed)

The dispute was closed without a decisive won/lost outcome, typically because the customer withdrew the claim, or the network closed it for procedural reasons. The disputed funds are generally returned to you, but you should monitor your balance to confirm.

​

Dispute fees

A flat dispute fee may apply per the terms of your account agreement, deducted as soon as the dispute is created, whether it is later won or lost. It is not charged again at resolution and is not refunded on a win. Refer to your merchant agreement for the specific fee structure that applies to your account.

---

​

Warning Disputes

Some payment networks issue a pre-dispute warning before a formal chargeback is filed. These appear in Bachs with the same needs_response status as a regular dispute. A warning dispute gives you a window to resolve the issue with the customer directly (often by issuing a refund) before the chargeback becomes formal. If you resolve it in time, the network may close the dispute without proceeding to a formal chargeback. You should treat warning disputes with the same urgency as regular disputes. The response_deadline_at field tells you how long you have.

---

​

Dispute Reason Codes

The reason field on a dispute reflects the reason code the customer gave when filing. Common reasons include: The reason code determines what evidence is most relevant to your response. See What Makes a Strong Response below.

---

​

Response Deadlines

Every dispute has a response_deadline_at timestamp. This is the hard deadline by which you must call Submit Dispute. Submitting after the deadline returns a 410 Gone error and your evidence will not be accepted. Deadlines are set by the payment network and are typically 7–21 days from when the dispute is opened, though this varies. Build alerting around the response_deadline_at field. Do not rely on checking disputes manually. The deadline can also move earlier after a dispute is created. If this happens, we will update the response_deadline_at field on the dispute record.

---

​

What Makes a Strong Response

The evidence you submit should directly address the reason for the dispute. A submission with no evidence, or evidence that does not speak to the stated reason, is unlikely to succeed. For fraudulent disputes:

• Proof of delivery or service fulfilment
• IP address and device data from checkout (include in notes)
• Signed agreements or terms acceptance records
• Prior non-disputed charges from the same customer

For product_not_received disputes:

• Delivery confirmation, tracking numbers, or access logs
• The date the product or service was provided (service_date)
• Communication with the customer confirming receipt

For subscription_cancelled disputes:

• Your cancellation policy as it was presented to the customer at purchase (cancellation_policy_disclosure)
• Proof that the cancellation was not received or processed before the billing date

For credit_not_processed disputes:

• Your refund policy (refund_policy_disclosure)
• Explanation of why a refund was not issued (refund_refusal_explanation)
• Any communication with the customer about the refund request

For all disputes:

• The customer’s name and email (customer_name, customer_email_address)
• Their billing address (billing_address)
• A clear product or service description (product_description)

Upload supporting documents (receipts, screenshots, email threads, signed agreements) via Upload Dispute Document and attach them using customer_communication_attachment_id, cancellation_policy_attachment_id, refund_policy_attachment_id, or uncategorized_attachment_id.

---

​

How It Works

---

​

Dispute Statuses

---

​

Prerequisites

• A valid API key. See Authentication Overview.
• An endpoint subscribed to dispute.created and dispute.updated if you want to learn about a dispute as it happens rather than by polling List Disputes.

---

​

Learning about a dispute programmatically

Besides polling with Get Dispute, a dispute drives dispute.created when it opens and dispute.updated on each status change, so you can react without polling.

---

---

​

In This Section

• List Disputes
• Get Dispute
• Upload Dispute Document
• Update Dispute Evidence
• Submit Dispute