Files

Returns a short-lived URL to PUT the file straight to storage. The bytes never pass through this API.

Three steps:

1. POST /files/upload-url with the purpose, name, MIME type and exact byte length.
2. PUT the bytes to upload_url with Content-Type and Content-Length set to the values you declared.
3. Pass file_url as cover_image_url (or inside image_urls) when you create the payment link or invoice.

Declare the length honestly. content_type and content_length are signed into the URL, so storage rejects a body of any other type or size — that is what enforces the cap once we are no longer in a position to measure it.

purpose picks the limits. It selects the storage location, the size cap and the MIME allowlist; a raw directory is never accepted, which is what keeps this endpoint away from unrelated areas such as KYB documents.

The URL expires (5 minutes by default). An expired URL is not an error you can retry on — ask for a new one.