Dispute

Dispute: Add File Evidence

Availability
Managing disputes via the API is only available to merchants who can access disputes in the Braintree Control Panel.
Note
More helpful information regarding disputes can be found in the dispute guide .

If you have text-based evidence like a refund number or shipment tracking number, use Dispute: Add Text Evidence.

If you have file-based evidence like an image or PDF, you must first create a document upload using the Document Upload: Create request. You will use the document upload id to attach the file to the dispute using the Dispute: Add File Evidence request as described later on this page.

You can only submit evidence for disputes that have a status of "open".
  1. Ruby
result = gateway.dispute.add_file_evidence(
    "a_dispute_id",
    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
    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.

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

Valid file evidence categoriesAnchorIcon

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.
CategoryDescription
`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).

File size limitationsAnchorIcon

Individual evidence files have a maximum of 4 megabytes (MB). Multiple files can be uploaded per dispute case. For any dispute, you can upload a total of 20 MB.

However, for some disputes you may be able to upload more evidence than the default limit of 20 MB. You can determine how much evidence you can upload at any given time in the Control Panel or in the response object under remaining_file_evidence_storage.

ExamplesAnchorIcon

Submitting categorized evidenceAnchorIcon

When responding to disputes with compelling evidence, specify the appropriate category for all evidence.
  1. Ruby
result = gateway.dispute.add_file_evidence(
    "a_dispute_id",
    category: "MERCHANT_WEBSITE_OR_APP_ACCESS",
    document_id: document.id,
)

Submitting uncategorized evidenceAnchorIcon

  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(
        "a_dispute_id",
        document_result.document_upload.id,
    )
end

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more