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

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

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.

Reason Code Permitted Categories
37 All categories
83 All categories except:
  • PROOF_OF_AUTHORIZED_SIGNER
    1040 All categories except:
    • PROOF_OF_AUTHORIZED_SIGNER
      1310 All categories except:
      • LEGIT_PAYMENTS_FOR_SAME_MERCHANDISE
      • PRIOR_NON_DISPUTED_TRANSACTION_ID
      • PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME
      • PRIOR_NON_DISPUTED_TRANSACTION_EMAIL_ADDRESS
      • PRIOR_NON_DISPUTED_TRANSACTION_IP_ADDRESS
      • PRIOR_NON_DISPUTED_TRANSACTION_PHONE_NUMBER
      • PRIOR_NON_DISPUTED_TRANSACTION_PHYSICAL_ADDRESS
      • RECURRING_TRANSACTION_ID
      • RECURRING_TRANSACTION_DATE_TIME
      • SIGNED_ORDER_FORM
        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
        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.*
        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.*

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

        Ruby
        Copy
        Copied
        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: document.id,
        )
        
        result = gateway.dispute.finalize("a_dispute_id")
        This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

        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.

        See also

        Next Page: Automating Dispute Management →

        Still have questions?

        If you can’t find an answer, contact our Support team