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 change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    Stripe::FileUpload.create({
        file: File.new("@/path/to/a/file.jpg"),
        purpose: 'dispute_evidence',
    })
    
    # Set your secret key: remember to change this 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.FileUpload.create(
        file=fp,
        purpose='dispute_evidence',
      )
    
    // Set your secret key: remember to change this 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\FileUpload::create([
        'file' => $fp,
        'purpose' => 'dispute_evidence',
    ]);
    
    // Set your secret key: remember to change this 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");
    FileUpload upload = FileUpload.create(params);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    const fp = fs.readFileSync('/path/to/a/file.jpg');
    stripe.fileUploads.create({
      file: {
        data: fp,
        name: 'file.jpg',
        type: 'application.octet-stream',
      },
      purpose: 'dispute_evidence',
    );
    
    // Set your secret key: remember to change this 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.FileUploadParams{
      FileReader: fp,
      Purpose: stripe.String(string(stripe.FileUploadPurposeDisputeEvidence)),
      Filename: stripe.String("file.jpg"),
    }
    upload, _ := fileupload.New(params)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var filename = "/path/to/a/file.jpg";
    using (FileStream stream = File.Open(filename, FileMode.Open)) {
      var service = new StripeFileUploadService();
      StripeFileUpload upload = service.Create(filename, stream, StripeFilePurpose.DisputeEvidence);
    }
    

    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 < 5MB
    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

    To retrieve 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_vTgdELaImDnCl3PnI8uq \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
    
    # Set your secret key: remember to change this 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::FileUpload.retrieve('file_vTgdELaImDnCl3PnI8uq')
    
    # Set your secret key: remember to change this 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.FileUpload.retrieve('file_vTgdELaImDnCl3PnI8uq')
    
    // Set your secret key: remember to change this 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\FileUpload::retrieve('file_vTgdELaImDnCl3PnI8uq');
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    FileUpload upload = FileUpload.retrieve("file_vTgdELaImDnCl3PnI8uq");
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    const upload = stripe.fileUploads.retrieve('file_vTgdELaImDnCl3PnI8uq')
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    upload, _ := fileupload.Get("file_vTgdELaImDnCl3PnI8uq", nil)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var service = new StripeFileUploadService();
    StripeFileUpload upload = service.Get("file_vTgdELaImDnCl3PnI8uq")
    

    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_xc3MPlFvWRwSqNOg7fs8 \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
       -d evidence[receipt]=file_vTgdELaImDnCl3PnI8uq
    
    # Set your secret key: remember to change this 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_xc3MPlFvWRwSqNOg7fs8', {
        evidence: { receipt: 'file_vTgdELaImDnCl3PnI8uq'},
    })
    
    # Set your secret key: remember to change this 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_xc3MPlFvWRwSqNOg7fs8',
      evidence={'receipt': 'file_vTgdELaImDnCl3PnI8uq'},
    )
    
    // Set your secret key: remember to change this 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_xc3MPlFvWRwSqNOg7fs8', [
        'evidence' => ['receipt' => 'file_vTgdELaImDnCl3PnI8uq'],
    ]);
    
    // Set your secret key: remember to change this 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_xc3MPlFvWRwSqNOg7fs8");
    Map<String, Object> evidenceParams = new HashMap<>();
    params.put("receipt", "file_vTgdELaImDnCl3PnI8uq");
    Map<String, Object> params = new HashMap<>();
    params.put("evidence", evidenceParams);
    dispute.update(params);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    stripe.disputes.update('dp_xc3MPlFvWRwSqNOg7fs8', {
      evidence: {
        receipt: 'file_vTgdELaImDnCl3PnI8uq',
      },
    );
    
    // Set your secret key: remember to change this 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_vTgdELaImDnCl3PnI8uq"),
      },
    }
    dis, _ := dispute.Update("dp_xc3MPlFvWRwSqNOg7fs8", params)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var options = new StripeDisputeUpdateOptions {
        Evidence = {
            Receipt = "file_vTgdELaImDnCl3PnI8uq",
        },
    };
    var service = new StripeDisputeService();
    StripeDispute dispute = service.Update("dp_xc3MPlFvWRwSqNOg7fs8", options);
    

    Note that you can only use an uploaded file in a single API request.

    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 also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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