Request a presigned upload for a supporting document

Attach a supporting document (invoice, contract, agreement, remittance advice or other evidence) to a transaction you own and receive a presigned upload for it. Accepted on any transaction of yours, RECEIVE and SEND alike; a document never gates or delays a payment.

Upload flow. (1) Compute the file's SHA-256 and base64-encode it (the S3 x-amz-checksum-sha256 wire format). (2) POST filename, content_type, file_size (exact byte length), checksum and document_type; the response is 201 with status PENDING, upload_url, upload_expires_at and required_headers. (3) HTTP PUT the raw file bytes to upload_url before upload_expires_at, carrying exactly the three required_headers (Content-Type, Content-Length, x-amz-checksum-sha256) with the values returned and no other signed headers; storage rejects a PUT whose headers differ or whose body does not hash to the declared checksum. (4) GET /customers/v1/transactions/{id}/documents: the next list call that finds the object with the declared checksum flips the document to AVAILABLE.

upload_url is valid until upload_expires_at (15 minutes by default; treat the timestamp as the upper bound and request a new upload if it lapses). Presigned URLs are not single-use: within the window the URL can be PUT again, but only with the identical bytes to the same location, because the checksum, length and content type are bound into the signature. Treat it as a secret and do not share it.

Not idempotent. This endpoint does not honour Idempotency-Key; every POST reserves a new document, so a retry creates a second record. At most 20 documents per transaction: the 21st POST is rejected with 400 (Transaction already has 20 documents; the cap is 20 per transaction), so do not retry a POST whose 201 you already received. filename is stored sanitised to [A-Za-z0-9._-] and capped at 128 characters. Files are retained for the configured period (5 years by default, see retention_until) and are never served back through the API.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Upload reserved. PUT the file to upload_url with exactly required_headers before upload_expires_at; the document stays PENDING until a list call verifies the stored object.

Bodyapplication/json

Example

{
    "id": "5c1f0a3e-8d2b-4f6a-9e07-2b3c4d5e6f70",
    "status": "PENDING",
    "upload_url": "https://example-bucket.s3.ap-southeast-2.amazonaws.com/.../invoice-4471.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost%3Bx-amz-checksum-sha256&X-Amz-Signature=...",
    "upload_expires_at": "2026-09-18T01:15:00.000Z",
    "required_headers": {
        "Content-Type": "application/pdf",
        "Content-Length": "184322",
        "x-amz-checksum-sha256": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found