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. 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://files.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", "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_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 files.stripe.com subdomain providing the file upload ID:

curl https://files.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");

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.