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::File.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.File.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\File::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");
File upload = File.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.files.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.FileParams{
  FileReader: fp,
  Purpose: stripe.String(string(stripe.FilePurposeDisputeEvidence)),
  Filename: stripe.String("file.jpg"),
}
upload, _ := file.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 = 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	< 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_3e8CE7oLikRIOeAzkbYP \
  -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::File.retrieve('file_3e8CE7oLikRIOeAzkbYP')

# 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.File.retrieve('file_3e8CE7oLikRIOeAzkbYP')

// 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\File::retrieve('file_3e8CE7oLikRIOeAzkbYP');

// 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";

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

// 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.files.retrieve('file_3e8CE7oLikRIOeAzkbYP')

// 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, _ := file.Get("file_3e8CE7oLikRIOeAzkbYP", 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 FileService();
File upload = service.Get("file_3e8CE7oLikRIOeAzkbYP");

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_fAawqUXb39j3z5YcCKAk \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d evidence[receipt]=file_3e8CE7oLikRIOeAzkbYP

# 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_fAawqUXb39j3z5YcCKAk', {
    evidence: { receipt: 'file_3e8CE7oLikRIOeAzkbYP'},
})

# 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_fAawqUXb39j3z5YcCKAk',
  evidence={'receipt': 'file_3e8CE7oLikRIOeAzkbYP'},
)

// 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_fAawqUXb39j3z5YcCKAk', [
    'evidence' => ['receipt' => 'file_3e8CE7oLikRIOeAzkbYP'],
]);

// 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_fAawqUXb39j3z5YcCKAk");
Map<String, Object> evidenceParams = new HashMap<>();
params.put("receipt", "file_3e8CE7oLikRIOeAzkbYP");
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_fAawqUXb39j3z5YcCKAk', {
  evidence: {
    receipt: 'file_3e8CE7oLikRIOeAzkbYP',
  },
);

// 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_3e8CE7oLikRIOeAzkbYP"),
  },
}
dis, _ := dispute.Update("dp_fAawqUXb39j3z5YcCKAk", 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 DisputeUpdateOptions {
    Evidence = new DisputeEvidenceOptions {
        ReceiptFileId = "file_3e8CE7oLikRIOeAzkbYP",
    },
};
var service = new DisputeService();
Dispute dispute = service.Update("dp_fAawqUXb39j3z5YcCKAk", options);

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