File Upload Guide

The File Upload API allows you to upload files to Stripe for a variety of purposes. When you upload a file, the API responds with a file token and other information about the file. 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, you’ll need to send a multipart/form-data request to https://uploads.stripe.com/v1/files. Note that the subdomain uploads.stripe.com is different than most of Stripe’s API endpoints. The request should specify a purpose and a file, where purpose is one of the following:

  • identity_document: for uploading a PNG or JPG image to prove your identity during account provisioning. The MIME type of the uploaded file should be either image/jpeg or image/png.
  • dispute_evidence: for uploading a PDF or image as evidence in a dispute. The MIME type of the uploaded file should be image/jpeg, image/png, or application/pdf.

To upload a file located at /path/to/a/file.jpg on your local file system with purpose identity_document, you can make the following curl request:

curl https://uploads.stripe.com/v1/files \
  -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
  -F purpose=identity_document \
  -F file="@/path/to/a/file.jpg"

Once you have sent the request, the server should return a JSON response which has the following form:

{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "created": 1420744487,
  "size": 1529506,
  "purpose": "identity_document",
  "url": null,
  "type": 'pdf'
}

The url parameter that is returned will contain a publicly accessible URL to view the uploaded file. For security purposes, the url parameter will return null for identity_document uploads.

The type parameter will return the media type of the file uploaded, and may be pdf, jpeg, or png. Note that for best results, all uploaded PDFs should adhere to the Adobe PDF 1.7 specifications (these are the same as the ISO 32000-1:2008 standards). Most modern PDF creators should default to creating PDFs conforming to this standard, but some older PDF creators may not work.

Retrieving a file

To retrieve a file, you should make a GET request to the uploads.stripe.com subdomain on the /v1/files endpoint using the token of the upload you’d like to retrieve. Here is an example curl request:

curl https://uploads.stripe.com/v1/files/fil_15BZxW2eZvKYlo2CvQbrn9dc \
  -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

Once this call is made, the server should return a response which is identical to the one received from uploading a file.

Using a file token

Once you’ve uploaded a file, you can use the returned ID in calls to the main Stripe API. For example, if you would like to attach an uploaded file to a particular dispute as evidence, you would make the following curl command:

curl https://uploads.stripe.com/v1/files/ch_18EJMJ2eZvKYlo2CcMyDMTIg/dispute \
  -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
  -d "stored_evidence[uncategorized_file]=fil_15BZxW2eZvKYlo2CvQbrn9dc"

Note that you can only attach an uploaded file once.