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

PHP
Copy
Copied
$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  "The transaction was already refunded"
);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

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.

PHP
Copy
Copied
if ($result->success) {
  # text based evidence added successfully
  $evidence = $result->evidence;
} else {
  echo $result->errors;
}

If the dispute can't be found, you'll receive a Braintree_Exception_NotFound exception.

important

Once you have finished uploading evidence, you must finalize the dispute using Dispute::finalize() before the Reply By date indicated in the dispute details.

Arguments
disputeId required, string

The unique dispute identifier.

Additional Parameters
'category' string

The category of this piece of evidence.

'content' required, string

The text-based content for the dispute evidence.

Valid text evidence categories

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.

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.

Examples

Submitting categorized evidence

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

PHP
Copy
Copied
$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  [
    'category' => 'PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME',
    'content' => '2016-01-01T22:00:00+0000'
  ]
);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Still have questions?

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