Dispute

Dispute: Add Text Evidence

availability

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

You can submit textual evidence for a dispute through this method. You can only submit evidence for disputes that have a status of "open".

  1. Ruby
result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  "The transaction was already refunded",
)

If the evidence is successfully added to the dispute, the result will be successful and will include the evidence object. Otherwise, check for validation errors.

  1. Ruby
if result.success?
  # text based evidence added successfully
  result.evidence
else
  p result.errors
end
Arguments
dispute_idrequired, String
The unique dispute identifier.
Additional Parameters
:categoryString
The category of this piece of evidence.
:contentString
The text-based content for the dispute evidence.

Valid text evidence categoriesanchor

If a dispute requires compelling evidence, use the following category codes to indicate what type of evidence you're submitting. Depending on the dispute reason code, additional validations may apply.

note

Not all disputes require categorized evidence. See the list of dispute reason codes that do require categorized, compelling evidence.

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.

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

Examplesanchor

Submitting categorized evidenceanchor

When responding to disputes with compelling evidence, specify the appropriate category for all evidence.

  1. Ruby
result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  category: "PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME",
  content: "2016-01-01T22:00:00+0000",
)