availability

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

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

Ruby
Copy
Copied
result = gateway.dispute.add_file_evidence(
  "a_dispute_id",
  document.id, # see the example below for more details
)
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.

Ruby
Copy
Copied
if result.success?
  # evidence file added successfully
  result.evidence
else
  p result.errors
end

If the dispute can't be found, it will raise a Braintree::NotFoundError.

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
dispute_id required, String

The unique dispute identifier.
Additional Parameters
:category String

The category of this piece of evidence.
:document_id required, String

The unique identifier for a DocumentUpload object. The document must have a kind of EvidenceDocument.

Compelling evidence categories

If a dispute requires compelling evidence, use the following category codes to indicate what type of evidence you’re submitting.

note

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

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
PRIOR_DIGITAL_GOODS_TRANSACTION_ARN ARN/Trace 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_ARN
DOWNLOAD_DATE_TIME The date and time the digital goods were downloaded
GEOGRAPHICAL_LOCATION The location of the device that downloaded the digital goods
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
PRIOR_NON_DISPUTED_TRANSACTION_ARN ARN/Trace ID of a previous non-disputed transaction for the same merchandise or service
PRIOR_NON_DISPUTED_TRANSACTION_DATE_TIME The date and time of the PRIOR_NON_DISPUTED_TRANSACTION_ARN
PRIOR_NON_DISPUTED_TRANSACTION_EMAIL_ADDRESS Email address used with the PRIOR_NON_DISPUTED_TRANSACTION_ARN
PRIOR_NON_DISPUTED_TRANSACTION_IP_ADDRESS IP address of the PRIOR_NON_DISPUTED_TRANSACTION_ARN
PRIOR_NON_DISPUTED_TRANSACTION_PHONE_NUMBER Phone number used with the PRIOR_NON_DISPUTED_TRANSACTION_ARN
PRIOR_NON_DISPUTED_TRANSACTION_PHYSICAL_ADDRESS Physical address used with the PRIOR_NON_DISPUTED_TRANSACTION_ARN
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
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_ARN The ARN/Trace ID used on a previous undisputed recurring transaction for the same merchandise or service
RECURRING_TRANSACTION_DATE_TIME The date and time of the RECURRING_TRANSACTION_ARN
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)

Examples

Submitting categorized evidence

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

Ruby
Copy
Copied
result = gateway.dispute.add_file_evidence(
  "a_dispute_id",
  category: "MERCHANT_WEBSITE_OR_APP_ACCESS",
  document_id: document.id,
)
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Submitting uncategorized evidence

Ruby
Copy
Copied
document_result = gateway.document_upload.create(
  kind: Braintree::DocumentUpload::Kind::EvidenceDocument,
  file: File.new("local_file.pdf", "r"),
)

if document_result.success?
  result = gateway.dispute.add_file_evidence(
    "a_dispute_id",
    document_result.document_upload.id,
  )
end
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