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.
When you set up dispute webhooks, you will receive automated notifications of dispute-related events at a designated endpoint on your server. There are 3 dispute webhooks available:
The Dispute Opened webhook will notify you 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.
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.
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
reply_by_date 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
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.
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:
- 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.