Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Quickstart
Stripe CLI
Stripe for Visual Studio Code
Webhooks
File uploads
Error handling
Error codes
API
Keys
Libraries
Upgrades
Rate limits
Card testing
Expanding responses
Domains and IP addresses
Building With Stripe
Stripe.js and Elements
Prebuilt iOS UI
Prebuilt Android UI
Extensions
Plugins
Samples
Checklist
HomeDeveloper tools

File upload guide

Use the File Upload API to securely send dispute evidence, identification documents, and more to Stripe.

Using your publishable key

We support the ability to upload files to Stripe directly from the browser. Write JavaScript that calls the appropriate endpoint and includes your publishable API key. However, if you want to create a file link when uploading a file, you have to use the secret key.

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_evidence:

Terminal
curl https://files.stripe.com/v1/files \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -F "file"="@/path/to/a/file.jpg" \ -F "purpose"="dispute_evidence"

The following example uploads a file using our Android SDK with the purpose dispute_evidence:

CheckoutActivity.kt
class CheckoutActivity : AppCompatActivity() { private val stripe: Stripe by lazy { Stripe(this,
"pk_test_TYooMQauvdEDq54NiTphI7jx"
) } private fun uploadFile(file: File) { stripe.createFile( StripeFileParams( file, StripeFilePurpose.DisputeEvidence ), callback = object : ApiResultCallback<StripeFile> { override fun onSuccess(result: StripeFile) { // File upload succeeded } override fun onError(e: Exception) { // File upload failed } } ) } }

There are several valid purpose values, each with file format and size requirements.

PurposeDescriptionSupported mimetypesMax sizeExpiryDownloadable
account_requirementAdditional documentation requirements that can be requested for an accountPDF
JPEG
PNG
16MBNEVERfalse
business_iconA business icon.JPEG
PNG
GIF
512KBNEVERtrue
business_logoA business logo.JPEG
PNG
GIF
512KBNEVERtrue
customer_signatureCustomer signature imageJPEG
PNG
4MBNEVERtrue
dispute_evidenceEvidence to submit with a dispute response.PDF
JPEG
PNG
8MB9 monthstrue
identity_documentA document to verify the identity of an account owner during account provisioning.PDF
JPEG
PNG
16MBNEVERfalse
pci_documentA self-assessment PCI questionnaire.PDF
16MBNEVERtrue
tax_document_user_uploadA user-uploaded tax document.PDF
CSV
JPEG
PNG
XLSX
DOCX
16MBNEVERtrue
additional_verificationAdditional verification for custom accountsPDF
JPEG
PNG
16MBNEVERfalse

identity_document 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 formatMIME type
CSVtext/csv
DOCXapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
GIFimage/gif
HTMLtext/html
JPEGimage/jpeg
JSONapplication/json
PDFapplication/pdf
PNGimage/png
TIFFimage/tiff
TSVtext/tab-separated-values
TXTtext/plain
XLSXapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
XMLapplication/xml
ZIPapplication/zip

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:

Terminal
curl https://files.stripe.com/v1/files/
{{FILE_ID}}
\ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc

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.

Terminal
curl https://files.stripe.com/v1/files/
{{FILE_ID}}
-u
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.

Terminal
curl https://api.stripe.com/v1/file_links \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
-d file=
{{FILE_ID}}

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:

Terminal
curl https://api.stripe.com/v1/disputes/
{{DISPUTE_ID}}
-u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
-d "evidence[receipt]"=
{{FILE_ID}}

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.
    • Print to PDF with macOS
    • Print to PDF with Adobe Acrobat
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Uploading a file
Retrieving a File API resource
Downloading File Contents
Using a file
Handling Upload Errors