Upload a file

Last updated: July 26, 2023

Note

A previous version of this page included a different file upload flow that has since been deprecated.

Use our Files API to upload supporting documentation required for full due diligence, or to connect a bank account as part of our Platforms solution.

When you upload a file, the API returns an id that represents that file. You can use this id to attach:

Identity documentation when creating or updating your sub-entity.
Company documentation when creating or updating a sub-entity that is a company.
Financial documentation when creating or updating a sub-entity that is an EU-based company.
Bank documentation when creating a payment instrument.

If you are uploading a bank statement to verify a set of bank details, subscribe to the following webhook events:

payment_instrument_verification_passed
payment_instrument_verification_failed

The API accepts the following types of documentation. Depending on the identification type, you may need to provide both the back and the front. Use the table below to find out more.

Type	Front required	Back required
Passport	Y	N
Driving license	Y	Y
National identity card	Y	Y
Citizen card	Y	Y
Residence permit	Y	Y
Electoral ID	Y	Y
Bank statement	Y	N

The uploaded file must be no larger than 4MB.

For identification documents, the file must be in JPEG, JPG, or PNG format.
For bank statements, company verification, and financial verification documents, the file must be in either JPEG, JPG, PNG, or PDF format.

Uploading a file is a two-step process:

Follow the steps to upload the document and receive an id. If the identification you are providing requires both the back and front, you will need to follow the process twice.

Note

Notice that the sub-domain – files.checkout.com – is slightly different to Checkout.com's other endpoints.

post

https://files.checkout.com/files

Your request should include:

the ID of the sub-entity you are uploading the file for
the purpose of the document

When uploading an identification document, set purpose to identity_verification. For a full list of possible fields, see our API reference.


1{
2  "entity_id": "ent_5plzb2y4dlqehanhm7i2swsuxc",
3  "purpose": "identity_verification"
4}

A successful response will include an upload URL.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}

Note

Only needed for sub-entities who have been onboarded as a company.


1{
2  "entity_id": "ent_5plzb2y4dlqehanhm7i2swsuxc",
3  "purpose": "company_verification"
4}

A successful response will include an upload URL.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}


1{
2  "entity_id": "ent_5plzb2y4dlqehanhm7i2swsuxc",
3  "purpose": "bank_verification"
4}

A successful response will include an upload URL.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}


1{
2  "entity_id": "ent_5plzb2y4dlqehanhm7i2swsuxc",
3  "purpose": "financial_verification"
4}

A successful response will include an upload URL.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}

Send a data-binary type request to the upload URL, with the file attached.


1curl --location --request PUT "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
2--data-binary '@/C:/Users/Test/test.pdf'

If your request is successful, you'll receive a 200 HTTP response code, indicating the file has been uploaded.

Use this endpoint to retrieve information about a previously uploaded file. A file can be in one of the following states:

Verified: the file is ready to be used in an onboarding request
Pending: the file is pending verification or virus scanning
Invalid: the status_reasons property will provide more information:
- invalid_mime_type: the mime type doesn't match the allowed content types for the specified document purpose – for example, a PDF document was uploaded for identity verification purpose
- file_size_limit_exceeded: the file is larger than 4MB
Failed verification: malicious file

To get a detailed view of all required and optional fields, see our API reference.

get

https://files.checkout.com/files/{file_id}


1{
2  "id": "file_bgwa24ijrknm6a3zlqydctnkou",
3  "mime_type": "image/jpeg",
4  "purpose": "identity_verification",
5  "size": 7111,
6  "status": "verified",
7  "uploaded_on": "2023-01-16T11:07:04.497Z",
8  "_links": {
9    "download": {
10      "href": "https://files.sandbox.checkout.com/files/ent_e5fxiiuec7yasswclx27zbpbcc/file_bbmcujt2fxmyh5pmeuz2bvvxd?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
11    },
12    "self": {
13      "href": "https://files.sandbox.checkout.com/files/file_bbmcujt2fxmyh5pmeuz2bvvxd"
14    }
15  }
16}


1{
2  "id": "file_a4q47zqvlgwdbladiuxrdjxxx",
3  "mime_type": "application/pdf",
4  "purpose": "identity_verification",
5  "size": 25692,
6  "status": "invalid",
7  "status_reasons": ["invalid_mime_type"],
8  "uploaded_on": "2023-01-16T11:01:32.226Z",
9  "_links": {
10    "self": {
11      "href": "https://files.sandbox.checkout.com/files/file_a4q47zqvlgwdbladiuxrdjxxx"
12    }
13  }
14}

Upload a file

Note

Before you begin

Types of identification and requirements

Upload a file

Note

Generate a file upload link

Request examples

Response example

Note

Response example

Response example

Response example

Attach the file

Request example

Retrieve a file

Response examples