Create a file

To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.

All of Stripe’s officially supported Client libraries support sending multipart/form-data.

Parameters

filehashRequired
A file to upload. Make sure that the specifications follow RFC 2388, which defines file transfers for the multipart/form-data protocol.

purposeenumRequired

The purpose of the uploaded file.

Possible enum values

account_requirement

Additional documentation requirements that can be requested for an account.

additional_verification

Additional verification for custom accounts.

business_icon

A business icon.

business_logo

A business logo.

customer_signature

Customer signature image.

dispute_evidence

Evidence to submit with a dispute response.

identity_document

A document to verify the identity of an account owner during account provisioning.

issuing_regulatory_reporting

Additional regulatory reporting requirements for Issuing.

pci_document

A self-assessment PCI questionnaire.

tax_document_user_upload

A user-uploaded tax document.

Show 2 more

More parameters

file_link_datahash

Returns

Returns the file object.

POST /v1/files

Server-side language

Stripe.api_key = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2"
file = File.new("@/path/to/a/file.jpg")
Stripe::File.create(
  {
    purpose: "dispute_evidence",
    file: file
  }
)

Response

{
  "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
  "object": "file",
  "created": 1680116847,
  "expires_at": 1703444847,
  "filename": "file.png",
  "links": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
  },
  "purpose": "dispute_evidence",
  "size": 8429,
  "title": null,
  "type": "png",
  "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
}

Retrieve a file

Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to access file contents.

Parameters

No parameters.

Returns

If the identifier you provide is valid, a file object returns. If not, Stripe raises an error.

GET /v1/files/:id

Server-side language

Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
file = Stripe::File.retrieve('file_1Mr4LDLkdIwHu7ixFCz0dZiH')

Response

{
  "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
  "object": "file",
  "created": 1680116847,
  "expires_at": 1703444847,
  "filename": "file.png",
  "links": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
  },
  "purpose": "dispute_evidence",
  "size": 8429,
  "title": null,
  "type": "png",
  "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
}

List all files

Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.

Parameters

purposestring
Filter queries by the file purpose. If you don’t provide a purpose, the queries return unfiltered files.

More parameters

createdhash

ending_beforestring

limitinteger

starting_afterstring

Returns

A hash with a data property that contains an array of up to limit files, starting after the starting_after file. Each entry in the array is a separate file object. If there aren’t additional available files, the resulting array is empty.

GET /v1/files

Server-side language

Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
files = Stripe::File.list({limit: 3})

Response

{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
      "object": "file",
      "created": 1680116847,
      "expires_at": 1703444847,
      "filename": "file.png",
      "links": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
      },
      "purpose": "dispute_evidence",
      "size": 8429,
      "title": null,
      "type": "png",
      "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
    }
  ]
}

File Links

To share the contents of a File object with non-Stripe users, you can create a FileLink. FileLinks contain a URL that you can use to retrieve the contents of the file without authentication.

Endpoints

POST/v1/file_links

POST/v1/file_links/:id

GET/v1/file_links/:id

GET/v1/file_links