Disputes

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:

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

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

categorized,evidence,flow

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 reason code.

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

37
83
1010
1030
1040
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 Dispute: Finalize 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.

Important Notice

Effective August 24th, 2024, the following changes will be made to evidence submissions for the specified reason codes:

Reason Codes 83, 1010, 1030, 1040:
- Merchants will no longer be allowed to submit evidence under the category LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE for these reason codes.
Reason Code 1310:
- This Reason code is removed from Compelling Evidence. In other words, evidence submission for all compelling evidence categories will no longer be accepted for this reason code. Instead, evidence must be submitted in following ways.
  - Control Panel:
    - Evidence can be provided through the Control Panel interface either by entering details in the text box or by uploading supporting documents.
  - API:
    - Text-based evidence must be submitted without a specific category.
    - File-based evidence can be submitted without a specific category or under the GENERAL category.

Please ensure your processes are updated to comply with these changes.

Reason Code	Permitted Categories
`37`	All categories
`83`	All categories except: `PROOF_OF_AUTHORIZED_SIGNER` `LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE`
`1010`	All categories except: `PROOF_OF_AUTHORIZED_SIGNER` `LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE`
`1030`	All categories except: `PROOF_OF_AUTHORIZED_SIGNER` `LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE`
`1040`	All categories except: `PROOF_OF_AUTHORIZED_SIGNER` `LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE`
`7030`	All categories
`C08`	All categories
`F29`	All categories
`UA02`	All categories
Empty reason code	All categories

Compelling file evidence categories

To submit evidence under the following categories, the evidence must be file-based and added to the dispute in a Dispute: Add File Evidence request. In general, a PDF or screenshot will suffice.

Category	Description
`LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE`	Evidence of spending across multiple payment types for the same merchandise.
`MERCHANT_WEBSITE_OR_APP_ACCESS`	Evidence of merchant website or app access.
`PROFILE_SETUP_OR_APP_ACCESS`	Evidence of a profile setup or app access.
`PROOF_OF_AUTHORIZED_SIGNER`	Evidence the transaction was completed by an authorized signer that the cardholder knows.
`PROOF_OF_DELIVERY_EMP_ADDRESS`	Proof of delivery to the cardholder's company address.
`PROOF_OF_DELIVERY`	Proof of delivery to the address on the AVS match.
`PROOF_OF_POSSESSION_OR_USAGE`	Proof that the customer is in possession of and/or using the merchandise.
`SIGNED_DELIVERY_FORM`	A signed delivery form, or a copy of the cardholder's ID as proof that the goods were picked up at your business location.
`SIGNED_ORDER_FORM`	A signed order form for a mail or phone transaction.
`TICKET_PROOF`	Evidence the ticket was received or scanned at gate, or evidence of other transactions related to the original (e.g. frequent flyer miles).

Compelling text evidence categories

To submit evidence under the following categories, the evidence must be text-based and added to the dispute in a Dispute: Add Text Evidence request.

Category	Description
`CARRIER_NAME`	Supply a carrier name with any relevant tracking details. List of Carriers.
`DEVICE_ID`	The identifier of the device that downloaded the digital goods.
`DEVICE_NAME`	The name of the device that downloaded the digital goods.
`DOWNLOAD_DATE_TIME`	The date and time the digital goods were downloaded. Also requires at least 2 of the following bulleted items: `DEVICE_ID` + `DEVICE_NAME` `MERCHANT_WEBSITE_OR_APP_ACCESS`(file-based evidence) `PRIOR_DIGITAL_GOODS_TRANSACTION_ID` + `PRIOR_DIGITAL_GOODS_TRANSACTION_DATE_TIME` `PROFILE_SETUP_OR_APP_ACCESS`(file-based evidence) `PURCHASER_IP_ADDRESS` + `GEOGRAPHICAL_LOCATION` `PURCHASER_NAME` + `PURCHASER_EMAIL_ADDRESS`
`GEOGRAPHICAL_LOCATION`	The latitude and longitude location of the device that downloaded the digital goods. Maximum 50 characters.
`PRIOR_DIGITAL_GOODS_TRANSACTION_ID`	The ID of a previous non-disputed digital goods transaction for the same merchandise or service.
`PRIOR_DIGITAL_GOODS_TRANSACTION_DATE_TIME`	The date and time of the `PRIOR_DIGITAL_GOODS_TRANSACTION_ID`.
`PRIOR_NON_DISPUTED_TRANSACTION_ID`	The ID of a previous non-disputed transaction for the same merchandise or service. Also requires `PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME` and at least one of the following bulleted items: `PRIOR_NON_DISPUTED_TRANSACTION_EMAIL_ADDRESS` `PRIOR_NON_DISPUTED_TRANSACTION_IP_ADDRESS` `PRIOR_NON_DISPUTED_TRANSACTION_PHONE_NUMBER` `PRIOR_NON_DISPUTED_TRANSACTION_PHYSICAL_ADDRESS` `PROOF_OF_DELIVERY`(file-based evidence)
`PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME`	The date and time of the `PRIOR_NON_DISPUTED_TRANSACTION_ID`.
`PRIOR_NON_DISPUTED_TRANSACTION_EMAIL_ADDRESS`	Email address used with the `PRIOR_NON_DISPUTED_TRANSACTION_ID`. Maximum 50 characters.
`PRIOR_NON_DISPUTED_TRANSACTION_IP_ADDRESS`	IP address of the `PRIOR_NON_DISPUTED_TRANSACTION_ID`.
`PRIOR_NON_DISPUTED_TRANSACTION_PHONE_NUMBER`	Phone number used with the `PRIOR_NON_DISPUTED_TRANSACTION_ID`.
`PRIOR_NON_DISPUTED_TRANSACTION_PHYSICAL_ADDRESS`	Physical address used with the `PRIOR_NON_DISPUTED_TRANSACTION_ID`.
`PURCHASER_EMAIL_ADDRESS`	The email address used for the digital goods.
`PURCHASER_IP_ADDRESS`	The IP address that purchased the digital goods.
`PURCHASER_NAME`	The name used for the digital goods.
`RECURRING_TRANSACTION_ID`	The ID of a previous undisputed recurring transaction for the same merchandise or service. Also requires `RECURRING_TRANSACTION_DATE_TIME`.
`RECURRING_TRANSACTION_DATE_TIME`	The date and time of the `RECURRING_TRANSACTION_ID`.
`TRACKING_NUMBER`	Supply any tracking details like shipping number or tracking number. Maximum 50 characters.
`TRACKING_URL`	Supply a publicly available tracking URL. Tracking URL starts with ftp:// or http:// or https:// followed by carrier's website.

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.

Ruby

result = gateway.dispute.add_text_evidence(
    "a_dispute_id",
    category: "PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME",
    content: "2016-01-01T22:00:00+0000",
)
result = gateway.dispute.add_text_evidence(
    "a_dispute_id",
    category: "PRIOR_NON_DISPUTED_TRANSACTION_ID",
    content: "a_transaction_id",
)
result = gateway.dispute.add_file_evidence(
    "a_dispute_id",
    category: "MERCHANT_WEBSITE_OR_APP_ACCESS",
    document_id: "http://document.id"
)
result = gateway.dispute.finalize("a_dispute_id")

When you're done adding evidence, you must call Dispute: Finalize before the reply-by date 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.