How to fight chargebacks on Braintree
A practical guide to Braintree disputes: dispute kinds and statuses, reply-by dates, reason codes, categorized evidence for recurring charges, and when to accept.
By Florian
A chargeback on a subscription is rarely about a stolen card. More often the customer forgot they signed up, did not recognise the descriptor, or thought they had cancelled. Those cases are winnable when you have the right records and submit them in the format Braintree expects. Braintree’s tooling is good, but strict: miss the date or put evidence in the wrong category and the response never reaches the bank.
This guide goes through how Braintree structures disputes, the evidence rules that matter for recurring billing, and a process you can run for every case. It sticks to Braintree’s own documentation: the disputes overview, Managing disputes via the API, Evidence requirements, the Dispute response object, Chargeback reason codes, Disputing chargebacks, Dispute: Accept and PayPal disputes (all accessed November 2026). For the basic API calls and webhook names, see the disputes section of recovering failed subscription payments on Braintree.
Dispute kinds and statuses
The dispute object has a kind and a status.
Kinds:
| Kind | What it is |
|---|---|
| Retrieval | A request for information about a transaction |
| Chargeback | The cardholder’s bank reverses the transaction |
| Pre-arbitration | A later stage, after a chargeback |
Statuses: Open, Accepted, Auto Accepted, Disputed, Won, Lost and Expired. “Disputed” means you have submitted evidence and are waiting for the bank’s decision. “Expired” means the reply-by date passed and you forfeited the right to contest.
PayPal transactions processed through Braintree follow PayPal’s own process, with three stages (retrieval, claim, chargeback) described in Braintree’s PayPal disputes guide. Braintree notes that retrievals and claims resolved through PayPal or your gateway do not incur dispute fees, while a dispute escalated to a chargeback may carry fees from the issuer or bank.
Pre-arbitration auto-accept
Per Braintree’s disputing chargebacks article, since August 27, 2025, Braintree auto-accepts pre-arbitrations under $1,000 for flat-rate merchants in the US, and a fee to process the pre-arbitration is charged regardless of the outcome. If you fall in that group, your effort belongs at the first chargeback response.
The reply-by date is the whole game
Every dispute has a reply-by date. According to Braintree, you must add your evidence and finalize before it, or your response is not considered by the bank. If you do not respond, an Accept response is sent on your behalf. Uploading evidence without finalizing counts as no response.
Practical rules:
- Use Dispute: Search filtered by reply-by date to list everything due in the next few days.
- Set an internal deadline two business days before the reply-by date.
- Evidence can only be added or removed (with Dispute: Remove Evidence) while the dispute is Open.
Reason codes that hit subscription businesses
The chargeback reason codes article and dispute reference list, among others:
- Cancelled recurring transaction: the cardholder says they were billed for a recurring charge they cancelled or tried to cancel. Card-brand codes listed by Braintree include Visa 41 and 1320, Mastercard 41 and 4841, Discover 4541 and American Express C28.
- Fraud / not authorised: the cardholder says they did not make the purchase.
- Not received: the cardholder says they did not get the product or service.
For subscriptions, “cancelled recurring” and “fraud” from customers who forgot the subscription are the common pair. Each needs different evidence.
Categorized evidence: the rule that trips teams up
Braintree’s evidence requirements say that when you respond to a fraud or non-receipt dispute, you must categorize each piece of evidence by the requirement it satisfies. A table in the same guide lists which categories each reason code accepts; using a category not allowed for that code is a validation error, and so is finalizing without valid evidence.
Two categories matter most for recurring billing:
RECURRING_TRANSACTION_ID: the ID of a previous undisputed recurring transaction for the same service.RECURRING_TRANSACTION_DATE_TIME: the date of that transaction. Braintree requires it whenever you provide a recurring transaction ID (or ARN); a response without it is rejected.
Proof of previously undisputed recurring transaction history is one of the evidence types Braintree lists for certain fraud and not-received disputes. In plain terms: if the same card paid you for months without complaint, say so, in the right category, with dates.
When you dispute through the Control Panel, Braintree adds transaction details such as AVS and CVV results to your response automatically.
What to submit, by reason
| Reason | Evidence that addresses it |
|---|---|
| Cancelled recurring transaction | Your cancellation policy as shown at sign-up; the customer’s account history showing no cancellation request before the charge (or the date they cancelled and that the charge preceded it); renewal reminders sent |
| Fraud (customer does not recognise it) | Prior undisputed recurring payments on the same card (categorized), sign-up details, login and usage after the disputed charge |
| Not received / service not provided | Usage logs for the billed period, access records, support conversations where the customer used the service |
Keep each document focused. A one-page summary that states the facts with dates, followed by the supporting records, is easier for a bank analyst to read than a long export.
When to accept instead
Dispute: Accept closes an Open dispute in the customer’s favour. Braintree’s docs add one important note: if you already refunded the transaction, do not accept; submit the refund as evidence instead. Accept when:
- the customer did cancel and you charged anyway (fix the bug, then refund any other affected customers);
- the evidence you have does not address the reason code;
- the amount is lower than the time a response would take, and you have no pattern to defend.
A process for every dispute
- Webhook in. On
dispute_opened, fetch the dispute and record kind, reason, amount and reply-by date. - Stop future charges if appropriate. A customer disputing a renewal is unlikely to pay the next one. Decide whether to cancel the subscription or pause access while the case is open.
- Gather records from billing, product usage, email and support, for the customer and the disputed period.
- Pick the categories allowed for this reason code and map each record to one.
- Write the summary, add text and file evidence.
- Finalize before your internal deadline.
- Track the outcome from
dispute_wonanddispute_lostwebhooks, by reason code. - Fix the cause. Unclear descriptor, missing renewal reminder, a cancel button that was hard to find: each lost dispute should change something. For prevention, see click-to-cancel rules and annual plan renewal reminders.
Test before you go live
Braintree’s sandbox can simulate outcomes: submitting the text compelling_evidence and finalizing moves a test dispute to Won, and losing_evidence simulates a loss (testing guide). Use it to check your categorization and finalize logic end to end.
Doing this with NoChurn
Braintree keeps the dispute, the decision and the funds. NoChurn follows Braintree dispute webhooks and gathers evidence automatically: cancel flow answers, emails sent, product usage and support conversations. It drafts a reply with AI, and nothing is sent to Braintree until a person on your team has reviewed and approved it. Support conversations come from read-only help desk connectors and are quoted as is. See NoChurn + Braintree.