Dispute: Add File Evidence


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

  1. Ruby
result = gateway.dispute.add_file_evidence(
  document.id, # see the example below for more details

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?
  # evidence file added successfully
  p result.errors
dispute_idrequired, String
The unique dispute identifier.
Additional Parameters
The category of this piece of evidence.

The unique identifier for a Document Upload object. The document must have a kind of EVIDENCE_DOCUMENT.

Valid file 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.


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

LEGIT_PAYMENTS_FOR_SAME_MERCHANDISEEvidence of spending across multiple payment types for the same merchandise.
MERCHANT_WEBSITE_OR_APP_ACCESSEvidence of merchant website or app access.
PROFILE_SETUP_OR_APP_ACCESSEvidence of a profile setup or app access.
PROOF_OF_AUTHORIZED_SIGNEREvidence the transaction was completed by an authorized signer that the cardholder knows.
PROOF_OF_DELIVERY_EMP_ADDRESSProof of delivery to the cardholder's company address.
PROOF_OF_DELIVERYProof of delivery to the address on the AVS match.
PROOF_OF_POSSESSION_OR_USAGEProof that the customer is in possession of and/or using the merchandise.
SIGNED_DELIVERY_FORMA 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_FORMA signed order form for a mail or phone transaction.
TICKET_PROOFEvidence the ticket was received or scanned at gate, or evidence of other transactions related to the original (e.g. frequent flyer miles).


Submitting categorized evidenceanchor

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

  1. Ruby
result = gateway.dispute.add_file_evidence(
  document_id: document.id,

Submitting uncategorized evidenceanchor

  1. Ruby
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(