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://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.