Disputes

availability

Managing disputes via the API is only available to merchants who can access disputes in the Braintree Control Panel.

Locate open disputesanchor

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 webhooksanchor

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 requestsanchor

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 disputesanchor

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 disputesanchor

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 evidenceanchor

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:

  1. Associate your evidence with the dispute
  2. Repeat as many times as necessary
  3. 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.

important

Braintree will not forward your response to the bank unless you have finalized it before the reply-by date passes.


Next Page: Evidence Requirements →