Overview

The Files API enables merchants to both upload and download files pertaining to their disputes. The Files API provides you with the following actions:

Explore the sections below to learn about the files endpoints and their requirements.

Basic Requirements

Authentication

All Files API endpoints require merchant authentication.

Idempotency

For idempotent requests, the idempotency key has an expiration date of 24 hours. Idempotency keys are passed in using the Idempotency-Key header.

Upload Dispute Evidence (Upload File)

POST /api/v1/files/upload

This endpoint is designed to upload the file (evidence) by making a multipart/form-data request on an open dispute.

Idempotency: Yes

Request Body Parameters:

Field Name	Data Type	Description
`file_name` required	string	Name of the file. The filename can be a maximum length of 25 characters long and may include alphanumeric characters, hyphens, underscores, spaces, and periods.
`file` required	string	A file to upload (binary format).
`purpose` required	string	An enum indicating the purpose of the uploaded file. Additional purpose enums can be added depending on the use case Value: -`dispute_evidence`
`merchant_id`	string	The ID of the merchant that the file is associated with.

Response Object:

Field Name	Data Type	Description
`file_id`	string	ID of the file.
`created`	string	Time at which the file is uploaded, in ISO 8601 UTC format.
`purpose`	string	The purpose of the file. Possible values: -`dispute_evidence`
`file_name`	string	Name of the file.

File Purpose Restrictions:

Field Purpose	Supported Mimetypes	Max Size
`dispute_evidence`	PDF	5MB

Download Dispute Evidence (Download File)

GET /api/v1/files/{file id}

Idempotency: No

Response Object:

Field Name	Data Type	Description
`id`	string	Unique identifier for the File object.
`download_url`	string	The URL from which the file can be downloaded.
`download_url_expires_at`	timestamp	A future timestamp after which the `download_url` will no longer be usable. (15 minutes)