Disputes
Locate open disputes
When a cardholder's bank informs Braintree of a new dispute against a merchant account, a dispute object is created for that account with a status of open
. From here, it is up to you to locate the dispute and decide how to respond to it.
By default, each new dispute will trigger an email notification to any email addresses or Control Panel users configured to receive dispute notifications for that merchant account. In addition to these email notifications, you can also:
- Set up dispute webhooks to be automatically notified at a designated endpoint on your server
- Use dispute search and find requests as a basis for your own custom logic
For more information on dispute email notifications for your account, refer to your bank-specific support articles or contact us.
Using dispute webhooks
When you set up dispute webhooks, you will receive automated notifications of dispute-related events at a designated endpoint on your server.
You can set up a Dispute Opened webhook to be notified of new disputes. To set it up, first make sure you've set up webhooks for your account in general by following our webhooks guide. Then, create a Dispute Opened webhook by following the process outlined on the Create page of that guide.
Read more about dispute webhooks in the reference.
Using dispute search and find requests
If you prefer to actively check for open disputes, you can locate them using search and find API requests:
- Use
Dispute: Search
to retrieve a collection of disputes based on criteria you specify - Use
Dispute: Find
to retrieve a single dispute by its ID
If any matching disputes are found, you will receive one or more dispute response objects.
Respond to open disputes
When a cardholder initiates a dispute, it's assigned a reason code, which Braintree returns on the dispute response object. This reason code helps the bank evaluate the claim and helps you, as the merchant, decide how to handle it. Our support articles have some general recommendations.
Each dispute has a deadline for responses. You must add your supporting evidence and finalize the dispute before this replyByDate()
in order for your response to be considered by the cardholder's bank. If you miss the deadline, you will forfeit your right to contest the cardholder's claim and the dispute status will be updated to expired
.
Accepting disputes
Sometimes, it is in your best interest to accept a dispute rather than fight it. You can do this using the Dispute: Accept
call.
Accepting a dispute indicates you don't wish to take any further action, but it doesn't necessarily imply you agree with the cardholder's claim. If you do not respond by the reply-by date of the dispute, an Accept response will be sent on your behalf and you will no longer be able to contest the dispute. Learn more about when it makes sense to accept disputes in our support articles.
Responding with evidence
If you do not wish to accept a dispute, you'll need to submit evidence showing why the dispute is not warranted. For most dispute reasons, you can submit whatever documentation you think will help your case. However, some reason codes require very specific documentation; see Evidence Requirements for details.
You can submit both text-based evidence and file-based evidence for disputes. At a high level, the process looks like this:
- Associate your evidence with the dispute
- If you have text-based evidence like a refund number or shipment tracking number, use
Dispute: Add Text Evidence
- If you have file-based evidence like an image or PDF, there are 2 steps to follow:
- Upload it to Braintree in a
Document Upload: Create
request - Attach the uploaded file to the dispute using
Dispute: Add File Evidence
- Upload it to Braintree in a
- If you have text-based evidence like a refund number or shipment tracking number, use
- Repeat as many times as necessary
- Finalize the dispute using
Dispute: Finalize
before the reply-by date indicated in the dispute details
Once you've finalized the dispute, we'll send your response and evidence along to the cardholder's bank for review.
Next Page: Evidence Requirements →