Handle 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 taken out of your available balance and set aside until the dispute is resolved, so you cannot pay it out in the meantime. A flat $15 dispute fee is deducted at the same time, whatever the outcome.

When you win (won)

The dispute was resolved in your favour. The amount set aside returns to your available balance. The dispute fee charged when the dispute was created is not refunded.

When you lose (lost)

The dispute was resolved against you. The amount set aside goes back to the customer. The dispute fee is not charged again, since it was deducted when the dispute was created.

When a dispute is closed (closed)

The dispute ended without a won or lost ruling, typically because the customer withdrew the claim or the network closed it for procedural reasons. Bachs reviews the case and releases any amount set aside. It is not released automatically, so contact support@bachs.io if you are waiting on it.

When a dispute is prevented (prevented)

The customer was refunded before any ruling. The refund moves the money, nothing else is set aside, and the dispute does not count toward your dispute rate.

Dispute fees

Each dispute costs a flat $15, 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. See Fees.

---

Warning disputes

Some card networks send an early dispute warning before a customer files a formal chargeback. A warning gives you a window to resolve the issue with the customer directly, often by issuing a refund, before it becomes a dispute. An early dispute warning has its own fee, charged once per payment. If a warned payment goes on to become a dispute, both fees apply. See Fees. Treat a warning with the same urgency as a dispute.

---

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. Saving or submitting evidence after the deadline returns 410 with error_code: DEADLINE_PASSED, and your evidence is not 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

• An API key with disputes:read to read disputes and disputes:write to upload documents, save evidence and submit. See Permissions.
• To act on a connected account’s disputes, send its ID in the X-Account-Id header. See Acting as an account.
• 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 sends dispute.created when it opens and dispute.updated when the network changes its status, so you can react without polling. Saving or submitting evidence does not send dispute.updated.

---

---

In this section

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