Upload Dispute Document

POSThttps://api.omise.co/disputes/:id/documents

Upload evidence documents to support your dispute response. Documents strengthen your case by providing proof to the card issuer.

---

🔑API Credentials

▼

---

Request Parameters

Required - 2 fieldsRequired Parameters

▼

`id`STRING(required)

Dispute ID (path parameter). The dispute must have status "open".

Example:"dspt_test_5xuy4w91xqz7d1w9u0t"

`file`FILE(required)

Evidence document file to upload. Accepted formats: PNG, JPG, PDF.

Example:"delivery-proof.pdf"

Constraints:Maximum file size: 10MB, Formats: PNG, JPG, PDF

Additional - 1 fieldAdditional Parameters

▼

---

Responses

200

Successful upload

Document uploaded successfully and attached to the dispute.

Response includes:

• id - Document ID (docu_*)
• filename - Original filename
• kind - Document type (if specified)
• download_uri - URL to download the document
• created_at - Upload timestamp
• Document is immediately available for bank review
• Cannot be deleted once uploaded

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• File missing or empty
• Invalid file format (not PNG, JPG, or PDF)
• Invalid kind parameter value

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Dispute not found.

Common causes:

• Incorrect dispute ID
• Dispute belongs to different account
• ID typo or formatting error

413

File too large

File size exceeds the 10MB limit.

Resolution:

• Compress the file to reduce size
• Split large documents into multiple files
• Ensure file is under 10MB

422

Unprocessable entity

Document cannot be uploaded to this dispute.

Common causes:

• Dispute status is not "open" (already pending, won, or lost)
• Dispute is closed
• Maximum number of documents reached

---

Code samples

cURL

curl https://api.omise.co/disputes/dspt_test_5xuy4w91xqz7d1w9u0t/documents \
  -X POST \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -F "file=@/path/to/delivery-proof.pdf" \
  -F "kind=proof_of_receipt"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

document = Omise::Dispute.upload_document('dspt_test_5xuy4w91xqz7d1w9u0t', {
  file: File.open('/path/to/delivery-proof.pdf'),
  kind: 'proof_of_receipt'
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

with open('/path/to/delivery-proof.pdf', 'rb') as file:
    document = omise.Dispute.upload_document(
        'dspt_test_5xuy4w91xqz7d1w9u0t',
        file=file,
        kind='proof_of_receipt'
    )

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});
const fs = require('fs');

const document = await omise.disputes.uploadDocument('dspt_test_5xuy4w91xqz7d1w9u0t', {
  file: fs.createReadStream('/path/to/delivery-proof.pdf'),
  kind: 'proof_of_receipt'
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$document = OmiseDispute::uploadDocument('dspt_test_5xuy4w91xqz7d1w9u0t', [
    'file' => '@/path/to/delivery-proof.pdf',
    'kind' => 'proof_of_receipt'
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

File file = new File("/path/to/delivery-proof.pdf");

Document document = client.disputes().uploadDocument(
    "dspt_test_5xuy4w91xqz7d1w9u0t",
    file,
    "proof_of_receipt"
);

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

using (var fileStream = File.OpenRead("/path/to/delivery-proof.pdf"))
{
    var document = await client.Disputes.UploadDocument(
        "dspt_test_5xuy4w91xqz7d1w9u0t",
        fileStream,
        "proof_of_receipt"
    );
}

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

file, _ := os.Open("/path/to/delivery-proof.pdf")
defer file.Close()

document, _ := client.UploadDisputeDocument("dspt_test_5xuy4w91xqz7d1w9u0t", file, "proof_of_receipt")

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Invalid file or parameters	Check file format and kind parameter
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Dispute not found	Check dispute ID is correct
file_too_large	File exceeds 10MB limit	Compress or split the file
invalid_file_format	Unsupported file format	Use PNG, JPG, or PDF
dispute_not_open	Dispute is not open	Documents can only be added to open disputes

Document Kind Values

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

---

Try it out

Required - 2 fields

▼

id(Required)

file(Required)

Additional - 1 fields

▼