Platforms

​

Manage all your sub-entities (also known as sub-merchants) through one integration, globally.

Platforms Operations

Onboard an entity

​

Onboard an entity so they can start using Checkout services.

Headers
  • Accept
    Type: string
    required

    Used to describe the type of content the client can interpret. Use the schema_version value to specify the payload format. The latest version is 3.0.

Body
required
application/json

The entity to be onboarded. Use the relevant format for the platform type, region and payload version.

    • reference
      Type: string · Unique reference
      min length:  
      1
      max length:  
      50
      required

      A unique reference you can later use to identify the sub-entity. Immutable after creation.

    • agreed_terms
      Type: object · Agreed Terms
      required

      Details of the person who agreed to the terms and conditions on behalf of the sub-entity, captured as evidence of consent to Checkout.com onboarding.

    • seller_category
      Type: string · Seller category
      required

      The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers.

    • profile
      Type: object · Profile
      required

      Information about the profile of the sub-entity, primarily regarding the products/services offered.

    • contact_details
      Type: object · Contact Details
      required

      Contact details of this sub-entity.

    • processing_details
      Type: object · Processing Details
      required

      Information about the sub-entity's expected processing.

    • company
      Type: object · Company
      required

      Information about the company represented by the sub-entity.

    • is_draft
      Type: boolean
      write-only

      Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.

    • documents
      Type: object · Documents

      Verification documents for the sub-entity.

Responses
  • application/json
  • 400

    Bad Request

  • 401

    Unauthorized

  • application/json
  • application/json
Request Example for post/accounts/entities
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities' \
  --request POST \
  --header 'Accept: application/json;schema_version=3.0' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "reference": "isv-seller-example001",
  "agreed_terms": {
    "date": "2026-07-02T10:30:00Z",
    "ip_address": "8.8.8.8",
    "name": "Toby Arden",
    "email": "toby.arden@example.com",
    "version": "cko-platform-terms-1.0.0"
  },
  "seller_category": "cat_retail_001",
  "processing_details": {
    "annual_processing_volume": 1000,
    "average_transaction_value": 2000,
    "average_order_fulfillment_time": 3,
    "target_countries": [
      "US"
    ],
    "currency": "USD",
    "payments": {
      "ach": {
        "annual_ach_volume": 100000,
        "average_ach_transaction_size": 5000,
        "estimated_monthly_credit_volume": 50000,
        "average_credit_amount": 2500
      }
    }
  },
  "contact_details": {
    "phone": {
      "number": "4155678900",
      "country_code": "US"
    },
    "email_addresses": {
      "primary": "toby.arden@example.com",
      "pci_compliance_contact": "pci.contact@example.com"
    }
  },
  "profile": {
    "urls": [
      "https://www.isv-seller-example.com"
    ],
    "mccs": [
      "5551"
    ],
    "holding_currencies": [
      "USD"
    ],
    "default_holding_currency": "USD"
  },
  "company": {
    "business_registration_number": "12-3456789",
    "business_type": "private_corporation",
    "legal_name": "ISV Seller Example Inc",
    "trading_name": "ISV Seller Example",
    "registered_address": {
      "address_line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "principal_address": {
      "address_line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "date_of_incorporation": {
      "year": 2025,
      "month": 10,
      "day": 1
    },
    "representatives": [
      {
        "roles": [
          "ubo",
          "control_person"
        ],
        "ownership_percentage": 25,
        "company_position": "ceo",
        "individual": {
          "first_name": "Toby",
          "last_name": "Arden",
          "email_address": "toby.arden@example.com",
          "national_id_type": "ssn",
          "national_id_number": "123456789",
          "date_of_birth": {
            "day": 15,
            "month": 1,
            "year": 1990
          },
          "place_of_birth": {
            "country": "US"
          },
          "citizenships": [
            {
              "country": "US"
            }
          ],
          "phone": {
            "country_code": "US",
            "number": "4155678901"
          },
          "address": {
            "address_line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
          }
        }
      },
      {
        "roles": [
          "authorised_signatory"
        ],
        "individual": {
          "first_name": "Alex",
          "last_name": "Morgan",
          "email_address": "alex.morgan@example.com",
          "national_id_type": "ssn",
          "national_id_number": "987654321",
          "date_of_birth": {
            "day": 22,
            "month": 6,
            "year": 1985
          },
          "place_of_birth": {
            "country": "US"
          },
          "citizenships": [
            {
              "country": "US"
            }
          ],
          "phone": {
            "country_code": "US",
            "number": "4155678902"
          },
          "address": {
            "address_line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
          }
        }
      }
    ]
  }
}'

{
  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "reference": "superhero1234",
  "requirements_due": [
    {
      "field": "individual.identification.document",
      "reason": "required",
      "message": "required"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
    }
  }
}

Entity onboarded successfully

Get sub-entity Members

​

Beta

Retrieve information on all users of a sub-entity that has been invited through Hosted Onboarding. Only one user can be invited to onboard the sub-entity through Hosted Onboarding.

To enable the Hosted Onboarding feature, contact your Account Manager.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the sub-entity

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Sub-entity not found

Request Example for get/accounts/entities/{entityId}/members
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/members' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "user_id": "usr_eyk754cqieqexfh6u46no5nnha"
    }
  ]
}

Sub-Entity member retrieved successfully

Reinvite a sub-entity member

​

Beta

Resend an invitation to the user of a sub-entity. The user will receive another email to continue their Hosted Onboarding application. An invitation can only be resent to the user originally registered to the sub-entity.

To enable the Hosted Onboarding feature, contact your Account Manager.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the sub-entity

  • userId
    Type: string
    required

    The ID of the invited user.

Body·
required
application/json
Empty object
Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Sub-entity not found

Request Example for put/accounts/entities/{entityId}/members/{userId}
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/members/usr_eyk754cqieqexfh6u46no5nnha' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{}'

{
  "id": "usr_eyk754cqieqexfh6u46no5nnha"
}

Sub-entity member retrieved successfully

Get entity details

​

Use this endpoint to retrieve an entity and its full details.

Path Parameters
  • id
    Type: string
    required

    The ID of the entity.

Headers
  • Accept
    Type: string
    required

    Used to describe the type of content the client can interpret. Use the schema_version value to specify the payload format. The latest version is 3.0.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Entity not found

  • application/json
Request Example for get/accounts/entities/{id}
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4' \
  --header 'Accept: application/json;schema_version=3.0' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "reference": "string",
  "status": "string",
  "profile": {
    "urls": [
      "https://example.com"
    ],
    "mccs": [
      "string"
    ],
    "default_holding_currency": 1,
    "holding_currencies": [
      "GBP"
    ]
  },
  "contact_details": {
    "phone": {
      "country_code": "GI",
      "number": "string"
    },
    "email_addresses": {
      "primary": 1
    },
    "invitee": {
      "email": 1
    }
  },
  "capabilities": {},
  "requirements_due": [
    {
      "field": "string",
      "reason": "string",
      "message": "string"
    }
  ],
  "company": {
    "legal_name": "string",
    "trading_name": "string",
    "business_registration_number": "string",
    "date_of_incorporation": {
      "day": 1,
      "month": 1,
      "year": 1500
    },
    "principal_address": {
      "address_line1": "string",
      "address_line2": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string"
    },
    "registered_address": {
      "address_line1": "string",
      "address_line2": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string"
    },
    "representatives": [
      {
        "id": "string",
        "individual": {
          "first_name": "string",
          "middle_name": "string",
          "last_name": "string",
          "date_of_birth": {
            "day": 1,
            "month": 1,
            "year": 1900
          },
          "place_of_birth": {
            "country": "string"
          },
          "national_id_number": "string",
          "email_address": 1,
          "phone": {
            "country_code": "AF",
            "number": "string"
          },
          "address": {
            "address_line1": "string",
            "address_line2": "string",
            "city": "string",
            "state": "string",
            "zip": "string",
            "country": "string"
          }
        },
        "company_position": "ceo",
        "roles": [
          "ubo"
        ],
        "ownership_percentage": 25,
        "documents": {
          "identity_verification": {
            "type": "passport",
            "front": "string",
            "back": "string"
          },
          "certified_authorised_signatory": {
            "type": "power_of_attorney",
            "front": "string"
          }
        }
      }
    ],
    "business_type": "individual_or_sole_proprietorship"
  },
  "processing_details": {
    "settlement_country": "string",
    "target_countries": [
      "string"
    ],
    "annual_processing_volume": 0,
    "average_transaction_value": 0,
    "highest_transaction_value": 0,
    "currency": "GBP"
  },
  "documents": {
    "company_verification": {
      "type": "incorporation_document",
      "front": "string"
    },
    "articles_of_association": {
      "type": "memorandum_of_association",
      "front": "string"
    },
    "bank_verification": {
      "type": "bank_statement",
      "front": "string"
    },
    "shareholder_structure": {
      "type": "certified_shareholder_structure",
      "front": "string"
    },
    "proof_of_legality": {
      "type": "proof_of_legality",
      "front": "string"
    },
    "proof_of_principal_address": {
      "type": "proof_of_address",
      "front": "string"
    },
    "additional_document1": {
      "front": "string"
    },
    "additional_document2": {
      "front": "string"
    },
    "additional_document3": {
      "front": "string"
    }
  }
}

Entity retrieved successfully

Update entity details

​

Update an entity.

Note: when you update a entity we may conduct further due diligence checks when necessary. During these checks, your payment capabilities will remain the same.

Path Parameters
  • id
    Type: string
    required

    The ID of the entity.

Headers
  • Accept
    Type: string
    required

    Used to describe the type of content the client can interpret. Use the schema_version value to specify the payload format. The latest version is 3.0.

Body
required
application/json

The entity to be updated. Use the relevant format for the platform type, region and payload version.

    • reference
      Type: string · Unique reference
      min length:  
      1
      max length:  
      50
      required

      A unique reference you can later use to identify the sub-entity. Immutable after creation.

    • agreed_terms
      Type: object · Agreed Terms
      required

      Details of the person who agreed to the terms and conditions on behalf of the sub-entity, captured as evidence of consent to Checkout.com onboarding.

    • seller_category
      Type: string · Seller category
      required

      The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers.

    • profile
      Type: object · Profile
      required

      Information about the profile of the sub-entity, primarily regarding the products/services offered.

    • contact_details
      Type: object · Contact Details
      required

      Contact details of this sub-entity.

    • processing_details
      Type: object · Processing Details
      required

      Information about the sub-entity's expected processing.

    • company
      Type: object · Company
      required

      Information about the company represented by the sub-entity.

    • is_draft
      Type: boolean
      write-only

      Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.

    • documents
      Type: object · Documents

      Verification documents for the sub-entity.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Entity not found

  • application/json
Request Example for put/accounts/entities/{id}
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4' \
  --request PUT \
  --header 'Accept: application/json;schema_version=3.0' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "reference": "isv-seller-example001",
  "agreed_terms": {
    "date": "2026-07-02T10:30:00Z",
    "ip_address": "8.8.8.8",
    "name": "Toby Arden",
    "email": "toby.arden@example.com",
    "version": "cko-platform-terms-1.0.0"
  },
  "seller_category": "cat_retail_001",
  "processing_details": {
    "annual_processing_volume": 1000,
    "average_transaction_value": 2000,
    "average_order_fulfillment_time": 3,
    "target_countries": [
      "US"
    ],
    "currency": "USD",
    "payments": {
      "ach": {
        "annual_ach_volume": 100000,
        "average_ach_transaction_size": 5000,
        "estimated_monthly_credit_volume": 50000,
        "average_credit_amount": 2500
      }
    }
  },
  "contact_details": {
    "phone": {
      "number": "4155678900",
      "country_code": "US"
    },
    "email_addresses": {
      "primary": "toby.arden@example.com",
      "pci_compliance_contact": "pci.contact@example.com"
    }
  },
  "profile": {
    "urls": [
      "https://www.isv-seller-example.com"
    ],
    "mccs": [
      "5551"
    ],
    "holding_currencies": [
      "USD"
    ],
    "default_holding_currency": "USD"
  },
  "company": {
    "business_registration_number": "12-3456789",
    "business_type": "private_corporation",
    "legal_name": "ISV Seller Example Inc",
    "trading_name": "ISV Seller Example",
    "registered_address": {
      "address_line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "principal_address": {
      "address_line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "date_of_incorporation": {
      "year": 2025,
      "month": 10,
      "day": 1
    },
    "representatives": [
      {
        "roles": [
          "ubo",
          "control_person"
        ],
        "ownership_percentage": 25,
        "company_position": "ceo",
        "individual": {
          "first_name": "Toby",
          "last_name": "Arden",
          "email_address": "toby.arden@example.com",
          "national_id_type": "ssn",
          "national_id_number": "123456789",
          "date_of_birth": {
            "day": 15,
            "month": 1,
            "year": 1990
          },
          "place_of_birth": {
            "country": "US"
          },
          "citizenships": [
            {
              "country": "US"
            }
          ],
          "phone": {
            "country_code": "US",
            "number": "4155678901"
          },
          "address": {
            "address_line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
          }
        }
      },
      {
        "roles": [
          "authorised_signatory"
        ],
        "individual": {
          "first_name": "Alex",
          "last_name": "Morgan",
          "email_address": "alex.morgan@example.com",
          "national_id_type": "ssn",
          "national_id_number": "987654321",
          "date_of_birth": {
            "day": 22,
            "month": 6,
            "year": 1985
          },
          "place_of_birth": {
            "country": "US"
          },
          "citizenships": [
            {
              "country": "US"
            }
          ],
          "phone": {
            "country_code": "US",
            "number": "4155678902"
          },
          "address": {
            "address_line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
          }
        }
      }
    ]
  }
}'

{
  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "reference": "superhero1234",
  "requirements_due": [
    {
      "field": "individual.identification.document",
      "reason": "required",
      "message": "required"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
    }
  }
}

Entity updated successfully

Get a list of requirements

​

Retrieve the list of pending requirements that the sub-entity must resolve. Requirements may be raised as part of onboarding, periodic AML reviews, or ongoing compliance checks. Each item in the response includes a priority and deadline to help you surface the most urgent items first.

Path Parameters
  • id
    Type: string
    required

    The sub-entity's ID.

Headers
  • Accept
    Type: string
    required

    Used to describe the type of content the client can interpret. Use the schema_version value to specify the payload format. The latest version is 3.0.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Sub-entity not found

Request Example for get/accounts/entities/{id}/requirements
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/requirements' \
  --header 'Accept: application/json;schema_version=3.0' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
      "resource": "ent_wxglze3wwywujg4nna5fb7ldli",
      "resource_type": "company",
      "reason": "periodic_review",
      "priority": "critical",
      "deadline": "2026-05-10T00:00:00Z",
      "urn": "urn:object:company#ent_wxglze3wwywujg4nna5fb7ldli#field:legal-name",
      "field_path": "company.legal_name",
      "field_urn": "urn:field:companies/legal-name",
      "metadata": {
        "purpose": "company_verification"
      },
      "_links": {
        "self": {
          "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
        }
      }
    }
  ]
}

Requirements retrieved successfully

Get requirement details

​

Retrieve detailed information for a single requirement, including the JSON Schema that defines the shape of the value expected when resolving it.

Once a response has been submitted for a requirement (see PUT /accounts/entities/{id}/requirements/{requirementId}), that requirement is no longer retrievable via this endpoint until it is re-issued or cleared.

Path Parameters
  • id
    Type: string
    required

    The sub-entity's ID.

  • requirementId
    Type: string
    required

    The requirement's ID, as returned by GET /accounts/entities/{id}/requirements.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Requirement not found, or a response has already been submitted for it.

Request Example for get/accounts/entities/{id}/requirements/{requirementId}
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
  "resource": "ent_wxglze3wwywujg4nna5fb7ldli",
  "resource_type": "company",
  "reason": "periodic_review",
  "priority": "high",
  "deadline": "2026-06-01T00:00:00Z",
  "urn": "urn:object:company#ent_wxglze3wwywujg4nna5fb7ldli#field:legal-name",
  "field_path": "company.legal_name",
  "field_urn": "urn:field:companies/legal-name",
  "metadata": {
    "purpose": "company_verification"
  },
  "message": "Please confirm your legal company name.",
  "_schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 200
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
    },
    "collection": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements"
    },
    "schema": {
      "href": "https://{prefix}.api.checkout.com/accounts/requirements/urn%3Aobject%3Acompany%23ent_wxglze3wwywujg4nna5fb7ldli%23field%3Alegal-name"
    }
  }
}

Requirement details retrieved successfully

Resolve a requirement

​

Submit a response to resolve a requirement. The shape of value is defined by the requirement's _schema, returned from GET /accounts/entities/{id}/requirements/{requirementId}.

The response is accepted for processing and applied asynchronously. While processing, the requirement is no longer retrievable via the GET endpoints; if validation fails downstream the requirement may reappear.

Path Parameters
  • id
    Type: string
    required

    The sub-entity's ID.

  • requirementId
    Type: string
    required

    The requirement's ID, as returned by GET /accounts/entities/{id}/requirements.

Body·
required
application/json

Request body used to resolve a requirement. The shape of value is defined by the requirement's _schema (returned from GET /accounts/entities/{id}/requirements/{requirementId}).

  • value
    required

    The response to the requirement. The expected shape depends on the requirement and is defined by the JSON Schema returned in the requirement details response. Common shapes include a file reference (for document uploads), a primitive value, or a structured object.

    The response to the requirement. The expected shape depends on the requirement and is defined by the JSON Schema returned in the requirement details response. Common shapes include a file reference (for document uploads), a primitive value, or a structured object.

    • propertyName
      Type: anything
Responses
  • application/json
  • 400

    The request body could not be parsed.

  • 401

    Unauthorized

  • 404

    Requirement not found, or a response has already been submitted for it.

  • application/json
Request Example for put/accounts/entities/{id}/requirements/{requirementId}
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "value": "Acme Holdings Limited"
}'

{
  "id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
  "status": "processing",
  "submitted_at": "2026-05-05T10:15:30Z",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
    },
    "collection": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements"
    }
  }
}

Response accepted for processing

Upload a file

​

Our Platforms solution provides an easy way to upload documentation required for full due diligence.

Use this endpoint to generate a file upload link, which you can then upload a file to using a data-binary type request.

See the documentation for more information.

Please note that the sub-domain – https://files.checkout.com – is slightly different to Checkout.com's other endpoints. See the documentation for more information.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the sub-entity

Body·
application/json
  • purpose
    Type: string enum
    required

    The purpose of the file upload.

    values
    • additional_document
    • articles_of_association
    • bank_verification
    • certified_authorised_signatory
    • company_ownership
Responses
  • application/json
  • 401

    Unauthorized

  • 422

    Unprocessable

  • 429

    Too many requests

Request Example for post/entities/{entityId}/files
curl https://files.checkout.com/entities/ent_w4jelhppmfiufdnatam37wrfc4/files \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "purpose": "identity_verification"
}'

{
  "id": "file_6lbss42ezvoufcb2beo76rvwly",
  "maximum_size_in_bytes": 4194304,
  "document_types_for_purpose": [
    "image/jpeg",
    "image/png",
    "image/jpg"
  ],
  "_links": {
    "upload": {
      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?AWSAccessKeyId=ASIX4BFJOBCQFLAMPKU3&Expires=1661355993&x-amz-security-token=some_token"
    },
    "self": {
      "href": "https://files.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
    }
  }
}

File uploaded successfully

Retrieve a file

​

Retrieve information about a previously uploaded file.

Please note that the sub-domain – https://files.checkout.com – is slightly different to Checkout.com's other endpoints. See the documentation for more information.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the sub-entity

  • fileId
    Type: string
    required

    The ID of the file. The value is always prefixed with file_.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    File not found

Request Example for get/entities/{entityId}/files/{fileId}
Shell Curl
curl https://files.checkout.com/entities/ent_w4jelhppmfiufdnatam37wrfc4/files/file_w4jelhppkaskd0dnatam37wrfc4 \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "file_6lbss42ezvoufcb2beo76rvwly",
  "status": "invalid",
  "status_reasons": [
    "InvalidMimeType"
  ],
  "size": 1024,
  "mime_type": "application/pdf",
  "uploaded_on": "2020-12-01T15:01:01Z",
  "purpose": "identity_verification",
  "_links": {
    "download": {
      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-clean-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?X-Amz-Expires=3600&x-amz-security-token=some_token"
    },
    "self": {
      "href": "https://files.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
    }
  }
}

OK