Skip to content

Upload a file to the Platforms solution

Beta

Last updated: February 15, 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:

Before you begin

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

Types of identification and requirements

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.

TypeFront requiredBack 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

Upload a file

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:

  1. Generate a file upload link.
  2. Attach the file.

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

Generate a file upload link

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.

Request examples

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

Response example

A successful response will include an upload URL.

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

Attach the file

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

Request example

1
curl --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.

Retrieve a file

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}

Response examples

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
}

Next steps

Update a sub-entity

Use the file id returned by the Files API to attach identity documentation required for full due diligence.

On this page

Before you begin
Types of identification and requirements
Upload a file
Retrieve a file
Next steps