Upload a file
POST
/v1/files multipart/form-data, 10 MB per file, pdf / jpg / png / tiff only — the card networks reject anything else, so we block it up front rather than letting you lose the dispute.
Pass the returned uid in file_ids when submitting dispute evidence. Files are kept for 180 days.
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Response 201
uid | string | |
purpose | dispute_evidence | What the file is for, fixed at upload time |
filename | string | |
size | integer | Size in bytes. 10 MB per file |
content_type | string | |
created_at | string<date-time> | |
expires_at | string<date-time> | Evidence is retained for 180 days, then purged automatically |
Errors
| 400 | Invalid parameters | |
Request
curl -X POST https://api.baton.example/v1/files \ -H "Authorization: Bearer sk_live_xxx" \ -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \ -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."
Response · 201
{
"uid": "file_9a21c7",
"purpose": "dispute_evidence",
"filename": "proof-of-delivery.pdf",
"size": 284117,
"content_type": "application/pdf",
"created_at": "2026-11-16T09:42:00Z",
"expires_at": "2027-05-15T09:42:00Z"
}