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
const 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. | 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 |
| 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_CRfrp0VfivLkrDTPkzBi \
-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_CRfrp0VfivLkrDTPkzBi')
# 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_CRfrp0VfivLkrDTPkzBi')
// 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_CRfrp0VfivLkrDTPkzBi');
// 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_CRfrp0VfivLkrDTPkzBi");
// 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
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
const upload = stripe.files.retrieve('file_CRfrp0VfivLkrDTPkzBi')
// 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_CRfrp0VfivLkrDTPkzBi", 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_CRfrp0VfivLkrDTPkzBi");
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_7I11eO12dyjOLIzyqRuW \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d evidence[receipt]=file_CRfrp0VfivLkrDTPkzBi
# 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_7I11eO12dyjOLIzyqRuW', {
evidence: { receipt: 'file_CRfrp0VfivLkrDTPkzBi'},
})
# 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_7I11eO12dyjOLIzyqRuW',
evidence={'receipt': 'file_CRfrp0VfivLkrDTPkzBi'},
)
// 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_7I11eO12dyjOLIzyqRuW', [
'evidence' => ['receipt' => 'file_CRfrp0VfivLkrDTPkzBi'],
]);
// 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_7I11eO12dyjOLIzyqRuW");
Map<String, Object> evidenceParams = new HashMap<>();
params.put("receipt", "file_CRfrp0VfivLkrDTPkzBi");
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
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
stripe.disputes.update('dp_7I11eO12dyjOLIzyqRuW', {
evidence: {
receipt: 'file_CRfrp0VfivLkrDTPkzBi',
},
);
// 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_CRfrp0VfivLkrDTPkzBi"),
},
}
dis, _ := dispute.Update("dp_7I11eO12dyjOLIzyqRuW", 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_CRfrp0VfivLkrDTPkzBi",
},
};
var service = new DisputeService();
Dispute dispute = service.Update("dp_7I11eO12dyjOLIzyqRuW", options);
Note that you can only use an uploaded file in a single API request.