Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper tools

File upload guide

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

Copy page

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:

Command Line
curl
curl https://files.stripe.com/v1/files \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -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
Kotlin
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 account.PDF
JPEG
PNG
16MBNEVERNo
business_iconA business icon.JPEG
PNG
GIF
512KBNEVERYes
business_logoA business logo.JPEG
PNG
GIF
512KBNEVERYes
customer_signatureCustomer signature image.JPEG
PNG
SVG
4MB7 daysYes
dispute_evidenceEvidence to submit with a dispute response.PDF
JPEG
PNG
5MB9 monthsYes
identity_documentA document to verify the identity of an account owner during account provisioning.PDF
JPEG
PNG
16MBNEVERWhen uploaded by Connect platform
issuing_regulatory_reportingAdditional regulatory reporting requirements for Issuing.JSON
256KB2 yearsYes
pci_documentA self-assessment PCI questionnaire.PDF
16MBNEVERYes
tax_document_user_uploadA user-uploaded tax document.PDF
CSV
JPEG
PNG
XLSX
DOCX
16MBNEVERYes
additional_verificationAdditional verification for custom accounts.PDF
JPEG
PNG
16MBNEVERNo
terminal_reader_splashscreenSplashscreen to be displayed on Terminal readers.PNG
JPEG
GIF
4.194304MB1 yearYes

Caution

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
APKapplication/vnd.android.package-archive
CSVtext/csv
DOCXapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
GIFimage/gif
HTMLtext/html
JPEGimage/jpeg
JSONapplication/json
JSONLapplication/jsonl
MARKDOWNtext/markdown
PDFapplication/pdf
PEMapplication/x-pem-file
PNGimage/png
SVGimage/svg+xml
TIFFimage/tiff
TSVtext/tab-separated-values
TXTtext/plain
WEBPimage/webp
XLSapplication/vnd.ms-excel
XLSMapplication/vnd.ms-excel.sheet.macroEnabled.12
XLSXapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
XMLapplication/xml
ZIPapplication/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:

Command Line
curl
curl https://files.stripe.com/v1/files/
{{FILE_ID}}
\ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2

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.

Command Line
curl https://files.stripe.com/v1/files/
{{FILE_ID}}
/contents
-u
sk_test_BQokikJOvBiI2HlWgH4olfQ2

If you want unauthenticated access to a file whose purpose allows downloading, then you can produce anonymous download links by creating a file_link.

Command Line
curl
curl https://api.stripe.com/v1/file_links \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
-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:

Command Line
curl
curl https://api.stripe.com/v1/disputes/
{{DISPUTE_ID}}
-u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
-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 can’t 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?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc