File upload guide
Use the File Upload API to securely send dispute evidence, identification documents, and more to Stripe.
When you upload a file to Stripe using the API, a file token and other information about the file is returned. The token can then be used in other API calls. This guide provides a detailed walk-through of this process.
Uploading a file
To upload a file, send a multipart/form-data
request to https://files.stripe.com/v1/files. Note that the subdomain files.stripe.com is different than most of Stripeâs API endpoints. The request should specify a purpose
and a file
. The following example uploads a file located at /path/to/a/file.jpg on your local file system with the purpose dispute_
:
The following example uploads a file using our Android SDK with the purpose dispute_
:
There are several valid purpose values, each with file format and size requirements.
Purpose | Description | Supported mimetypes | Max size | Expiry | Downloadable |
---|---|---|---|---|---|
account_ | Additional documentation requirements that can be requested for an account. | PDF JPEG PNG | 16MB | NEVER | false |
business_ | A business icon. | JPEG PNG GIF | 512KB | NEVER | true |
business_ | A business logo. | JPEG PNG GIF | 512KB | NEVER | true |
customer_ | Customer signature image. | JPEG PNG SVG | 4MB | 7 days | true |
dispute_ | Evidence to submit with a dispute response. | PDF JPEG PNG | 5MB | 9 months | true |
identity_ | A document to verify the identity of an account owner during account provisioning. | PDF JPEG PNG | 16MB | NEVER | false |
issuing_ | Additional regulatory reporting requirements for Issuing. | JSON | 256KB | 2 years | true |
pci_ | A self-assessment PCI questionnaire. | PDF | 16MB | NEVER | true |
tax_ | A user-uploaded tax document. | PDF CSV JPEG PNG XLSX DOCX | 16MB | NEVER | true |
additional_ | Additional verification for custom accounts. | PDF JPEG PNG | 16MB | NEVER | false |
terminal_ | Splashscreen to be displayed on Terminal readers. | PNG JPEG GIF | 4.194304MB | 1 year | true |
Caution
identity_
images also need to be smaller than 8,000px by 8,000px.
The MIME type of the file you wish to upload must correspond to its file format.
File format | MIME type |
---|---|
APK | application/vnd.android.package-archive |
CSV | text/csv |
DOCX | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
GIF | image/gif |
HTML | text/html |
JPEG | image/jpeg |
JSON | application/json |
JSONL | application/jsonl |
MARKDOWN | text/markdown |
application/pdf | |
PEM | application/x-pem-file |
PNG | image/png |
SVG | image/svg+xml |
TIFF | image/tiff |
TSV | text/tab-separated-values |
TXT | text/plain |
WEBP | image/webp |
XLS | application/vnd.ms-excel |
XLSM | application/vnd.ms-excel.sheet.macroEnabled.12 |
XLSX | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
XML | application/xml |
ZIP | application/zip |
Caution
Any Microsoft Office documents containing VBA macros will be rejected due to security concerns.
A successful request returns a file object.
Retrieving a File API resource
To retrieve the API resource for a File, make a GET request to the /v1/files endpoint of the files.stripe.com subdomain providing the file upload ID:
When using restricted API keys, you must receive prior access to the Files
resource.
Downloading File Contents
If the file purpose allows downloading the file contents, then the file includes a non-null url
field indicating how to access the contents. This url requires authentication with your Stripe API keys.
curl https://files.stripe.com/v1/files/
/contents -u{{FILE_ID}}sk_test_4eC39HqLyjWDarjtT1zdp7dc
If you want unauthenticated access to a file whose purpose allows downloading, then you can produce anonymous download links by creating a file_link.
The file_link resource has a url
field that will allow unauthenticated access to the contents of the file.
Using a file
After a file is uploaded, the file upload ID can be used in other API requests. For example, to attach an uploaded file to a particular dispute as evidence:
Note that you can only use an uploaded file in a single API request.
Handling Upload Errors
When you use the File API to upload a PDF document, we run it through a series of checks to validate that it is correctly formatted and meets PDF specifications. We return an error for uploads that fail any of our checks.
Try the following to fix errors that we detect:
- Remove annotations or additional media you added to the document.
- If you cannot remove your annotations or media, or if you combined several PDFs into one, try using your computerâs Print to PDF function to create a fresh document.