File upload guide

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. If you need to generate a file link for an uploaded file, you need to call the upload API from your integrations back end instead, following best practices by using a restricted API key that has Files: Write permission or a well-protected secret API key.

When you upload a file to Stripe using the API, it returns a file token and other information about the file. You can then use the token in other API calls. This guide describes this process.

Upload a file

To upload a file, send a multipart/form-data request to https://files.stripe.com/v1/files. The subdomain files.stripe.com is different than most Stripe API endpoints. Specify a purpose and a file in the request. The following example uploads a file located at /path/to/a/file.jpg on your local file system with the purpose dispute_evidence:

curl https://files.stripe.com/v1/files \
  -u sk_test_wU7nrJCZspk1NPDxiQgAF05q: \
  -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:

class CheckoutActivity : AppCompatActivity() {
    private val stripe: Stripe by lazy {
        Stripe(this, "pk_test_YVzIqUTwiCYcEXO1DPqDrM98")
    }

    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.

The MIME type of the file you want to upload must correspond to its file format.

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:

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

When using restricted API keys, you must receive prior access to the Files resource.

Download the 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/
{{FILE_ID}}
/contents
  -u sk_test_wU7nrJCZspk1NPDxiQgAF05q

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

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

The file_link resource has a url field that allows unauthenticated access to the contents of the file.

Using a file

After you upload a file, you can use the file upload ID in other API requests. For example, to attach an uploaded file to a particular dispute as evidence:

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

You can only use an uploaded file in a single API request.

Handle Upload Errors

When you use the File API to upload a PDF document, we run it through a series of checks to validate that its 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 cant remove your annotations or media, or if you combined several PDFs into one, try using your computers Print to PDF function to create a fresh document.
  • Print to PDF with macOS
  • Print to PDF with Adobe Acrobat