File Upload Guide

    Use the File Upload API to securely send dispute evidence, identification documents, and more to Stripe. If you need help after reading this, search our documentation or check out answers to common questions. You can even chat live with other developers in #stripe on freenode.

    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://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. There are several valid purpose values, the two most common being:

    • identity_document, 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. The maximum allowed file size is 8MB.
    • dispute_evidence, 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. The maximum allowed file size is 4MB.

    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://uploads.stripe.com/v1/files \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -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_BQokikJOvBiI2HlWgH4olfQ2"
    
    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_BQokikJOvBiI2HlWgH4olfQ2"
    
    with open("/path/to/a/file.jpg", "r") 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_BQokikJOvBiI2HlWgH4olfQ2");
    
    $fp = fopen("/path/to/a/file.jpg", "r");
    \Stripe\FileUpload::create(array(
      "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_BQokikJOvBiI2HlWgH4olfQ2";
    
    Map<String, Object> params = new HashMap<String, Object>();
    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_BQokikJOvBiI2HlWgH4olfQ2");
    
    var fp = fs.readFileSync("/path/to/a/file.jpg");
    stripe.fileUploads.create({
      file: {
        data: fp,
        name: "file.jpg",
        type: "application/octet-stream",
      },
      purpose: "dispute_evidence",
    }, function(err, fileUpload) {
      // asynchronously called
    });
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    fp, _ := os.Open("/path/to/a/file.jpg")
    params := &stripe.FileUploadParams{
      File: fp,
      Purpose: "dispute_evidence",
    }
    file_upload, err := fileupload.New(params)
    

    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 uploads.stripe.com subdomain providing the file upload ID:

    curl https://uploads.stripe.com/v1/files/file_AASCUqb2c7J4Lw \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
    
    # 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    file = Stripe::FileUpload.retrieve("file_AASCUqb2c7J4Lw")
    
    # 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    file = stripe.FileUpload.retrieve("file_AASCUqb2c7J4Lw")
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2");
    
    $file = \Stripe\FileUpload::retrieve("file_AASCUqb2c7J4Lw");
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2";
    
    FileUpload upload = FileUpload.retrieve("file_AASCUqb2c7J4Lw");
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2");
    
    var file = stripe.fileUploads.retrieve({"file_AASCUqb2c7J4Lw"}, function(err, fileUpload) {
      // asynchronously called
    });
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    file, err := fileupload.Get("file_AASCUqb2c7J4Lw", nil)
    

    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_89I0mulhz0ttaV \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d evidence[receipt]=file_AASCUqb2c7J4Lw
    
    # 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    dispute = Stripe::Dispute.retrieve("dp_89I0mulhz0ttaV")
    dispute.evidence = {
      :receipt => "file_AASCUqb2c7J4Lw",
    }
    dispute.save
    
    # 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    dispute = stripe.Dispute.retrieve("dp_89I0mulhz0ttaV")
    dispute.evidence = {
      receipt: "file_AASCUqb2c7J4Lw",
    }
    dispute.save()
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2");
    
    $dispute = \Stripe\Dispute::retrieve("dp_89I0mulhz0ttaV");
    $dispute->evidence = array(
      "receipt" => "file_AASCUqb2c7J4Lw",
    );
    $dispute->save();
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2";
    
    Dispute dispute = Dispute.retrieve("dp_89I0mulhz0ttaV");
    
    Map<String, Object> params = new HashMap<String, Object>();
    Map<String, Object> evidence = new HashMap<String, Object>();
    evidence.put("receipt", "file_AASCUqb2c7J4Lw");
    params.put("evidence", evidence)
    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_BQokikJOvBiI2HlWgH4olfQ2");
    
    stripe.disputes.update("dp_89I0mulhz0ttaV", {
      evidence: {
        receipt: "file_AASCUqb2c7J4Lw",
      }
    }, function(err, dispute) {
      // asynchronously called
    });
    
    // 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_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.DisputeParams{
      Evidence: &stripe.DisputeEvidenceParams{
        Receipt: "file_AASCUqb2c7J4Lw",
      },
    }
    dispute, err := dispute.Update("dp_89I0mulhz0ttaV", params)
    

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