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

Disputes are a standard part of doing business, especially if you accept payments online. It's every merchant's responsibility to review each chargeback, retrieval, and pre-arbitration opened against them and decide whether to accept it or to submit evidence against the customer’s claim.

The way you manage disputes depends on your Braintree merchant account setup. If you currently manage your disputes in the Braintree Control Panel, you can also do so via the API.

The API offers the same functionality as the Control Panel. You can:

  • Find a dispute, or search for disputes that match specific criteria
  • Check a dispute's status
  • Submit evidence to defend the dispute
  • Accept a dispute

The rest of this guide focuses on using the API to manage disputes. For more information on disputes in general or dispute management in the Control Panel, see our support articles.

Dispute management flowanchor

For merchants who can manage their disputes via Braintree, the basic process looks like this:

typical merchant flow

  1. A cardholder initiates a dispute with their bank, and a dispute is created for the merchant account that processed the transaction
  2. The merchant decides whether to accept or respond to the dispute
    • If the merchant accepts the dispute, the process ends here
    • If the merchant decides to respond:
      1. The merchant adds text or file evidence against the cardholder's claim
      2. The merchant finalizes the dispute, and Braintree sends the response to the cardholder's bank for review


Your account setup determines whether you can manage your disputes via Braintree, or whether you need to follow a different process:

  • If you currently use the Braintree Control Panel to accept and dispute chargebacks, you can use the API to manage disputes.
  • If you currently follow any other process to respond to chargebacks, you cannot use the API to manage disputes.
  • If you’re not sure how your business currently handles chargebacks, contact us for assistance.

If you implement dispute management via the API but your account setup doesn't support managing disputes that way, you may miss the opportunity to recover funds from illegitimate chargebacks.

Next Page: Managing Disputes via the API →