Skip to main content

Disputes

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 GraphQL APIs.

The APIs offer 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 APIs to manage disputes. For more information on disputes in general or dispute management in the Control Panel, see our support articles.

Dispute management flow

For merchants who can manage their disputes via Braintree, the basic process looks like the following.

dispute_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

Availability

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.

IMPORTANT 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.

Managing Disputes via GraphQL APIs

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. For more information on dispute email notifications for your account, refer to your bank-specific support articles or contact us.

Locate open disputes

Use dispute search and find requests as a basis for your own custom logic.

Find single dispute by ID

You can find a dispute by its global ID using the following node query.

query

query QueryDispute {
  node(id: "ZGlzcHV0ZV91c19iYW5rX2Rpc3B1dGVfd2l0aF9jdXN0b21lcg") {
    ... on Dispute {
      id
      amountDisputed {
        value
        currencyCode
      }
      createdAt
      receivedDate
      replyByDate
      referenceNumber
      responseDeadline
      processorResponse {
        reasonCode
        reasonDescription
        receivedDate
        referenceNumber
      }
    }
  }
}

Note that the ID is provided in the query itself. No need for separate input.

response

{
    "data": {
        "node": {
            "id": "ZGlzcHV0ZV91c19iYW5rX2Rpc3B1dGVfd2l0aF9jdXN0b21lcg",
            "amountDisputed": {
                "value": "100.00",
                "currencyCode": "USD"
            },
            "createdAt": "2022-09-06T19:10:56.000000Z",
            "receivedDate": "2022-09-04",
            "replyByDate": "2022-09-16",
            "referenceNumber": "6",
            "responseDeadline": "2022-09-15T05:59:59.000000Z",
            "processorResponse": {
                "reasonCode": "60",
                "reasonDescription": null,
                "receivedDate": "2022-09-04",
                "referenceNumber": "6"
            }
        }
    },
    "extensions": {
        "requestId": "d62d5dc1-e818-4b67-8c5e-7b0379dc6820"
    }
}

Search for multiple disputes

Using GraphQL Search API, you can customize your search queries to meet your needs. Below is an example of a search query by a combination of status, receivedDate and replyByDate.

query

query SearchDisputes($input: DisputeSearchInput!) {
  search {
    disputes(input: $input) {
      edges {
        node {
          ... on Dispute {
            id
            amountDisputed {
              value
              currencyCode
            }
            createdAt
            receivedDate
            replyByDate
            referenceNumber
            responseDeadline
            processorResponse {
              reasonCode
              receivedDate
              referenceNumber
            }
          }
        }
      }
    }
  }
}

variables

{
  "input": {
	"status": {
      "in": ["OPEN"]
    },
    "receivedDate": {
        "greaterThanOrEqualTo": "2022-09-04"
    },
    "replyByDate": {
        "lessThanOrEqualTo": "2022-09-16"
    }
  }
}

response

{
    "data": {
        "search": {
            "disputes": {
                "edges": [
                    {
                        "node": {
                            "id": "ZGlzcHV0ZV9kaXNwdXRlX3dpdGhfc291cmNl",
                            "amountDisputed": {
                                "value": "100.00",
                                "currencyCode": "USD"
                            },
                            "createdAt": "2022-09-06T19:10:56.000000Z",
                            "receivedDate": "2022-09-04",
                            "replyByDate": "2022-09-16",
                            "referenceNumber": "10",
                            "responseDeadline": "2022-09-15T05:59:59.000000Z",
                            "processorResponse": {
                                "reasonCode": "60",
                                "receivedDate": "2022-09-04",
                                "referenceNumber": "10"
                            }
                        }
                    },
                    {
                        "node": {
                            "id": "ZGlzcHV0ZV9kaXNwdXRlX3dpdGhfcGF5bWVudF9pbnN0cnVtZW50",
                            "amountDisputed": {
                                "value": "100.00",
                                "currencyCode": "USD"
                            },
                            "createdAt": "2022-09-06T19:10:56.000000Z",
                            "receivedDate": "2022-09-04",
                            "replyByDate": "2022-09-16",
                            "referenceNumber": "7",
                            "responseDeadline": "2022-09-15T05:59:59.000000Z",
                            "processorResponse": {
                                "reasonCode": "60",
                                "receivedDate": "2022-09-04",
                                "referenceNumber": "7"
                            }
                        }
                    }
                ]
            }
        }
    },
    "extensions": {
        "requestId": "82befacf-4b99-4db9-a377-e7e59f814d23"
    }
}

GraphQL Search supports a large combination of search criteria. See DisputSearchInput for more details.

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 acceptDispute mutation.

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 replyByDate 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:

  1. Associate your evidence with the dispute
  2. Repeat as many times as necessary
  3. Finalize the dispute using finalizeDispute mutation before the replyByDate 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.