— No Results

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

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

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::File.create({
  file: File.new('/path/to/a/file.jpg'),
  purpose: 'dispute_evidence',
})

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

with open('/path/to/a/file.jpg', 'rb') as fp:
  stripe.File.create(
    file=fp,
    purpose='dispute_evidence',
  )

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$fp = fopen('/path/to/a/file.jpg', 'r');
\Stripe\File::create([
  'file' => $fp,
  'purpose' => 'dispute_evidence',
]);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Map<String, Object> params = new HashMap<>();
params.put("file", new File("/path/to/a/file.jpg"));
params.put("purpose", "dispute_evidence");
File upload = File.create(params);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const fp = fs.readFileSync('/path/to/a/file.jpg');
stripe.files.create({
  file: {
    data: fp,
    name: 'file.jpg',
    type: 'application.octet-stream',
  },
  purpose: 'dispute_evidence',
});

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

fp, _ := os.Open("/path/to/a/file.jpg")
params := &stripe.FileParams{
  FileReader: fp,
  Purpose: stripe.String(string(stripe.FilePurposeDisputeEvidence)),
  Filename: stripe.String("file.jpg"),
}
upload, _ := file.New(params)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var filename = "/path/to/a/file.jpg";
using (FileStream stream = System.IO.File.Open(filename, FileMode.Open))
{
    var service = new FileService();
    var options = new FileCreateOptions
    {
        File = stream,
        Purpose = FilePurpose.DisputeEvidence,
    };
    Stripe.File upload = service.Create(options);
}

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

    Purpose Description Supported File Formats Max Size
    business_logo A business logo. GIF, JPEG, PNG 512KB
    customer_signature A customer signature. JPG, PNG 4MB
    dispute_evidence Evidence to submit with a dispute response. JPEG, PDF, PNG 8MB
    identity_document A document to verify the identity of an account owner during account provisioning. JPEG, PNG < 10MB
    pci_document A self-assessment PCI questionnaire. PDF 16MB
    tax_document_user_upload A user-uploaded tax document. CSV, DOCX, JPG, PDF, PNG, XLS, XLSX, 16MB

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

    File Format MIME Type
    CSV text/csv
    DOCX application/vnd.openxmlformats-officedocument.wordprocessingml.document
    GIF image/gif
    JPEG image/jpeg
    PDF application/pdf
    PNG image/png
    XLS application/vnd.ms-excel
    XLSX application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

    A successful request returns a file_upload 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_7dw2DIIUozNbfSxHCLYT \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

upload = Stripe::File.retrieve('file_7dw2DIIUozNbfSxHCLYT')

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

upload = stripe.File.retrieve('file_7dw2DIIUozNbfSxHCLYT')

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$upload = \Stripe\File::retrieve('file_7dw2DIIUozNbfSxHCLYT');

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

File upload = File.retrieve("file_7dw2DIIUozNbfSxHCLYT");

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const upload = await stripe.files.retrieve('file_7dw2DIIUozNbfSxHCLYT');

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

upload, _ := file.Get("file_7dw2DIIUozNbfSxHCLYT", nil)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var service = new FileService();
var upload = service.Get("file_7dw2DIIUozNbfSxHCLYT");

    Downloading File Contents

    If the file purpose allows downloading the file contents, then the file_upload will have 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_7dw2DIIUozNbfSxHCLYT/contents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  --output "my_file.png"

    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_4eC39HqLyjWDarjtT1zdp7dc: \
  -d file=file_7dw2DIIUozNbfSxHCLYT

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::FileLink.create({
  file: 'file_7dw2DIIUozNbfSxHCLYT',
})

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.FileLink.create(
  file='file_7dw2DIIUozNbfSxHCLYT',
)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

StripeFileLink::create([
  'file' => 'file_7dw2DIIUozNbfSxHCLYT',
]);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Map<String, Object> filelinkParams = new HashMap<String, Object>();
filelinkParams.put("file", "file_7dw2DIIUozNbfSxHCLYT");

FileLink.create(filelinkParams);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const fileLink = await stripe.fileLinks.create({
  file: 'file_7dw2DIIUozNbfSxHCLYT',
});

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.FileLinkParams{
  File: stripe.String("file_7dw2DIIUozNbfSxHCLYT"),
}
filelink.New(params)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new FileLinkCreateOptions
{
  File = "file_7dw2DIIUozNbfSxHCLYT",
};

var service = new FileLinkService();
var fileLink = service.Create(options);

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

    Using a file

    Once you’ve uploaded 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/dp_YHkWV0MDzkdh2aort5qo \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "evidence[receipt]"=file_7dw2DIIUozNbfSxHCLYT

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Dispute.update('dp_YHkWV0MDzkdh2aort5qo', {
  evidence: { receipt: 'file_7dw2DIIUozNbfSxHCLYT'},
})

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Dispute.modify('dp_YHkWV0MDzkdh2aort5qo',
  evidence={'receipt': 'file_7dw2DIIUozNbfSxHCLYT'},
)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Dispute::update('dp_YHkWV0MDzkdh2aort5qo', [
  'evidence' => ['receipt' => 'file_7dw2DIIUozNbfSxHCLYT'],
]);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Dispute dispute = Dispute.retrieve("dp_YHkWV0MDzkdh2aort5qo");
Map<String, Object> evidenceParams = new HashMap<>();
evidenceParams.put("receipt", "file_7dw2DIIUozNbfSxHCLYT");

Map<String, Object> params = new HashMap<>();
params.put("evidence", evidenceParams);
dispute.update(params);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.disputes.update(
  'dp_YHkWV0MDzkdh2aort5qo',
  {
    evidence: {
      receipt: 'file_7dw2DIIUozNbfSxHCLYT',
    },
  }
);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.DisputeParams{
  Evidence: &stripe.DisputeEvidenceParams{
    Receipt: stripe.String("file_7dw2DIIUozNbfSxHCLYT"),
  },
}
dis, _ := dispute.Update("dp_YHkWV0MDzkdh2aort5qo", params)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new DisputeUpdateOptions
{
    Evidence = new DisputeEvidenceOptions
    {
        Receipt = "file_7dw2DIIUozNbfSxHCLYT",
    },
};
var service = new DisputeService();
var dispute = service.Update("dp_YHkWV0MDzkdh2aort5qo", options);

    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 will 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 have added to the document
    • If you cannot remove your annotations or media, or if you’ve combined several PDFs into one, try using your computer’s Print to PDF function to create a fresh document.

    Was this page helpful?
    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team.

    You can chat live with other developers in #stripe on freenode or subscribe to our YouTube channel.

    On this page