Documents API

The Documents API enables creating, retrieving, and deleting document files to help resolve disputes. Documents such as scanned receipts, shipment delivery slips, and customer correspondence are used as evidence in the dispute resolution process.

Overview

Documents are files uploaded to support your case during a dispute. When a customer files a chargeback, providing strong documentary evidence increases your chances of winning the dispute.

Supported File Types

Format	MIME Type	Max Size
PNG	image/png	10MB
JPG/JPEG	image/jpeg	10MB
PDF	application/pdf	10MB

Document Types

Use the kind parameter to categorize your evidence:

Kind	Description	Example Documents
cardholder_details	Customer identity verification	Customer ID, billing address proof
details_of_purchase	Transaction and order details	Invoice, order confirmation, receipt
proof_of_receipt	Delivery or service confirmation	Tracking info, signed delivery receipt
proof_of_acceptance	Customer acknowledgment	Email correspondence, terms acceptance

Available Endpoints

• Upload a Document - POST /disputes/:id/documents
• Retrieve a Document - GET /disputes/:id/documents/:document_id
• List Documents - GET /disputes/:id/documents
• Destroy a Document - DELETE /disputes/:id/documents/:document_id

Document Object

Field	Type	Description
object	string	Always "document"
id	string	Document identifier (docu_*)
livemode	boolean	Whether this is a live or test mode document
location	string	API path to retrieve the document
deleted	boolean	Whether the document has been deleted
filename	string	Original filename of uploaded document
kind	string	Document type (cardholder_details, etc.)
download_uri	string	Temporary URL to download the document
created_at	string	When the document was uploaded (ISO 8601)

Best Practices

Uploading Evidence

• Provide clear, legible documents - Ensure images are high quality and text is readable
• Use descriptive filenames - Helps organize and identify documents
• Categorize correctly - Use the appropriate kind value
• Upload promptly - Don't wait until the deadline

Recommended Evidence by Dispute Type

Dispute Reason	Recommended Evidence
Fraudulent	Signed delivery receipt, AVS/CVV verification, customer communication
Product not received	Tracking number, delivery confirmation, shipping carrier records
Product unacceptable	Product description, photos, return policy, customer correspondence
Duplicate charge	Transaction records showing single charge
Credit not processed	Refund confirmation, policy documentation

Important Notes

• Documents can only be uploaded to disputes with open status
• Once a dispute moves to pending, documents cannot be modified
• Download URLs are temporary and expire
• Maximum file size is 10MB per document

Related Resources

• Disputes API
• Dispute Management Guide

---

Need help? Contact support@omise.co for assistance with dispute evidence.