Dispute Evidence Requirements

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

Overview

Certain dispute reason codes – ones related to fraud and to merchandise/services not received – have very specific evidence requirements:

1. If you choose to respond to the dispute, you must submit appropriately-formatted documentation that meets the card brands’ definitions of compelling evidence.
2. You must categorize each piece of evidence to indicate which specific requirement it satisfies.
3. 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.

Why some disputes require compelling evidence

These compelling evidence requirements were introduced by Visa as part of their Visa Claims Resolution (VCR) initiative in early 2018. The rules are intended to help reduce the complexity of the dispute process as well as to hold card-issuing banks to consistent standards. You can read more about the VCR initiative on our blog.

Braintree enforces these requirements on all Visa, Mastercard, Discover, and American Express disputes. If you do not submit the required pieces of compelling evidence or categorize them appropriately, you may receive validation errors and ultimately are unlikely to win the dispute.

How to manage disputes that require compelling evidence

Identifying disputes that require compelling evidence

Visa, Mastercard, Discover, and Amex disputes related to fraud and merchandise/services not received require compelling evidence. These disputes can be identified by their reasonCode which is part of processorResponse of the dispute response object.

Below is a full list of reason codes that require compelling evidence:

• 37
• 83
• 1040
• 1310
• 7030
• C08
• F29
• UA02
• Empty reason codes

If a dispute has any other reason code, there are no specific evidence requirements, and the evidence does not need to be categorized.

Choosing what compelling evidence to submit

Most dispute reason codes that require compelling evidence permit all categories of evidence. However, some reason codes only permit evidence in specific categories.

If you have initiated a refund via Braintree, and the refund has a status of Submitted_For_Settlement, Settling, or Settled, the refund is automatically detected when you open a dispute and the evidence will be added to your submission to the processor. You may add additional compelling evidence according to the guidelines below, or call finalizeDispute mutation without adding additional evidence to submit your dispute.

If you issued the refund outside of Braintree, and the disputed transaction requires compelling evidence, you are responsible for providing evidence of the refund. Contact us for assistance with the dispute.

NOTE Compelling evidence must also be in an appropriate format for the category. Some categories require file-based evidence, while the others require text-based evidence.

Compelling file evidence categories

To submit evidence under the following categories, the evidence must be file-based and added to the dispute using createDisputeFileEvidence mutation. In general, a PDF or screenshot will suffice.

Compelling text evidence categories

To submit evidence under the following categories, the evidence must be text-based and added to the dispute using createDisputeTextEvidence mutation.

* Whenever possible, Braintree internally maps transaction IDs to their corresponding acquirer reference numbers (ARNs) to allow processing partners to reference the transactions. If your integration already passes ARNs directly to Braintree, it can continue to do so, but passing transaction IDs is simpler. If the ID you provide cannot be located in your vault, the ID itself will be saved as the ARN.

Submitting compelling evidence

When adding compelling evidence to a dispute, be sure to specify the appropriate category for the piece of evidence you are submitting.

Steps you might take in submitting evidence is shown below.

// call createDisputeTextEvidence mutation & repeat as needed
// call createDisputeFileEvidence mutation & repeat as needed
// call finalizeDispute mutation to complete evidence submission

To actually submit text evidence, use the following example as template, if you wish.

mutation CreateDisputeTextEvidend ($input: CreateDisputeTextEvidenceInput!) {
  createDisputeTextEvidence(input: $input) {
    evidence {
      id
      createdAt
      content
      category
    }
  }
}

{
  "input": {
    "disputeId": "ZGlzcHV0ZV9kaXNwdXRlX3dpdGhfcGF5bWVudF9pbnN0cnVtZW50",
    "category": "DEVICE_NAME",
    "content": "i have proof!"
  }
}

{
    "data": {
        "createDisputeTextEvidence": {
            "evidence": {
                "id": "ZGlzcHV0ZWV2aWRlbmNlX201ZDQ5Zm04emNybXFtems",
                "createdAt": "2022-09-09T00:16:39.000000Z",
                "content": "i have proof!",
                "category": "DEVICE_NAME"
            }
        }
    },
    "extensions": {
        "requestId": "7fd5c3ae-d487-4df3-b8f6-b882da5f9703"
    }
}

To upload a file as evidence, use createDisputeFileEvidence mutation. For more details, checkout Uploading Files for Mutations page.

When you’re done adding evidence, you must finalizeDispute mutation before the replyByDate indicated in the dispute details. Braintree will not forward your response to the bank unless you have finalized it before the reply-by date passes.

Dispute Evidence Recommendations

In addition to the above guidance for disputes, we provide a Dispute Evidence Recommendations offering (currently in beta) that uses numerous machine learning models to guide you in deciding which kinds of evidence will likely help you win a given dispute. Learn more about Dispute Evidence Recommendations.