Onboard a sub-entity using the API

Last updated: December 24, 2025

You can submit an application to onboard a sub-entity using the Platforms API.

Information

You can also onboard sub-entities without code using the Dashboard.

Submit the sub-entity's onboarding application using the API.
Checkout.com performs verification checks on the sub-entity.
You receive webhooks as the checks progress.

Note

Your sub-entity cannot process payments until it has passed the verification checks.

Ensure you've completed the following steps before submitting the application.

Your account is able to onboard sub-entities.
You have received your client_id and client_secret, which you need to generate access tokens with the required scopes. See OAuth 2.0 client credentials for more information.
You have received one or more processing channel IDs.
You have configured yourwebhook server and subscribed to the relevant events.

The Platforms API uses OAuth authentication. Call the Onboard an entity endpoint.

In the request body, select the platform type, region, and account type. Provide the required fields.

Information

You can only set profile.mccs and either company.principal_address.country or individual.principal_address.country (depending on the platform type) to the values that were configured for your scope when onboarding your platform.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

post

https://[prefix].api.checkout.com/accounts/entities


1{
2  "reference": "CAKE12345",
3  "contact_details": {
4    "phone": {
5      "number": "7700900000"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": [ "https://www.thecakeshop.com" ],
13    "mccs": [ "5814" ]
14  },
15  "company": {
16    "business_registration_number": "12345678",
17    "legal_name": "The Cake Shop Inc.",
18    "trading_name": "The Cake Shop",
19    "principal_address": {
20      "address_line1": "654 Example St.",
21      "city": "Edinburgh",
22      "zip": "EH9 2XY",
23      "country": "GB"
24    },
25    "registered_address": {
26      "address_line1": "123 High St.",
27      "city": "London",
28      "zip": "W1T4TJ",
29      "zip": "SW1A 1AA",
30      "country": "GB"
31    },
32    "representatives": [
33      {
34        "first_name": "Ali",
35        "last_name": "Farid",
36        "address": {
37          "country": "GB"
38        }
39      }
40    ]
41  }
42}


1{
2  "reference": "DONUTS12345",
3  "contact_details": {
4    "phone": {
5      "number": "7700900000"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.ali-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Ali",
17    "last_name": "Farid",
18    "trading_name": "Ali's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "123 High St.",
22      "city": "London",
23      "zip": "SW1A 1AA",
24      "country": "GB"
25    }
26  }
27}


1{
2  "reference": "cakeshop678910",
3  "contact_details": {
4    "phone": {
5      "number": "111222333"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.thecakeshop.com"],
13    "mccs": ["5814"]
14  },
15  "company": {
16    "legal_name": "The Cake Shop Inc.",
17    "trading_name": "The Cake Shop",
18    "principal_address": {
19      "address_line1": "90 Tottenham Court Road",
20      "city": "London",
21      "zip": "W1T4TJ",
22      "country": "GB"
23    }
24  }
25}


1{
2  "reference": "cakeshop0123456",
3  "contact_details": {
4    "phone": {
5      "number": "2345678910"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.daniels-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Daniel",
17    "last_name": "Yubi",
18    "trading_name": "Daniel's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "90 Tottenham Court Road",
22      "city": "London",
23      "zip": "W1T4TJ",
24      "country": "GB"
25    }
26  }
27}

You can receive one of the following HTTP responses:

201 – Application submitted successfully
409 – Conflict
422 – Invalid data was sent


1{
2  "id": "ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
3  "reference": "0123456",
4  "status": "pending",
5  "capabilities": {
6    "payments": {
7      "available": true,
8      "enabled": false
9    },
10    "payouts": {
11      "available": false,
12      "enabled": false
13    }
14  },
15  "requirements_due": [],
16  "_links": {
17    "self": {
18      "href": "https://[prefix].api.sandbox.checkout.com/accounts/entities/ent_vv2jjkuf2gzj5tcw2x7ptua7zy"
19    }
20  }
21}

A successful response returns:

id field – The sub-entity ID, which you need for future requests.
capabilities object – Indicates whether the sub-entity’s capabilities are enabled. Capabilities are only enabled after the sub-entity passes the verification checks.
status field – The status is pending, while awaiting the verification checks. For all possible statuses, see Sub-entity status.

You also receive a Sub-entity created webhook.


1{
2  "id": "ent_nofjig36ypra6236f4tfm5bvui",
3  "reference": "678910",
4  "status": "requirements_due",
5  "capabilities": {
6    "payments": {
7      "enabled": false
8    },
9    "payouts": {
10      "enabled": false
11    }
12  },
13  "requirements_due": [
14    {
15      "field": "company.representatives[0].identification.document",
16      "reason": "required"
17    }
18  ],
19  "_links": {
20    "self": {
21      "href": "https://[prefix].api.sandbox.checkout.com/accounts/entities/ent_nofjig36ypra6236f4tfm5bvui"
22    }
23  }
24}

A successful response returns:

id field – The sub-entity ID, which you need for future requests.
capabilities object – Indicates whether the sub-entity’s capabilities are enabled. Capabilities are only enabled after the sub-entity passes the verification checks.
status field – The status is requirements_due. You must now add supporting documentation so that Checkout.com can start the verification checks.

For all possible statuses, see Sub-entity status.

You also receive a Sub-entity created webhook.


1{
2  "_links": {
3    "self": {
4      "href": "https://[prefix].api.sandbox.checkout.com/accounts/entities/ent_lcvk7ay5zcglzvda6n7o5ws2hq"
5    }
6  }
7}

If you receive a 409 response, you provided a reference that has already been used for another sub-entity. The reference must be a unique alphanumeric value . Try again with a different reference.


1{
2  "request_id": "0HM72UMS6H39C:00000003",
3  "error_type": "invalid_request",
4  "error_codes": ["reference_required"]
5}

If you receive a 422 response, ensure you have provided all required fields in your request.

The response also returns an error_codes array with one or more specific errors. For more information, see Possible error codes.

You can receive the following error codes when onboarding a sub-entity:

Error code	Description
`profile_mccs_invalid_for_processing_scope`	The MCCs you provided for the sub-entity are outside your platforms's processing scope.
`profile_default_holding_currency_invalid_for_currency_scope`	The default holding currency you provided for the sub-entity is outside your platform's currency scope.
`principal_address_country_invalid_for_processing_scope`	The principal address country you provided for the sub-entity is outside your platform's processing scope.
`client_entity_cannot_onboard_subentities`	Your platform is not permitted to onboard new sub-entities.
`company_or_individual_required`	You must provide the `company` or `individual` object in your request.
`sub_entity_invalid`	There was an internal validation error. Contact your account manager or request support.
`<field_name>_invalid`	The specified field has uses invalid formatting, or an invalid minimum or maximum length. For example, `legal_name_invalid`, or `profile_urls_0_invalid`. The exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`. You must provide the `company` or `individual` object in your request.
`<field_name>_required`	The specified field is required, but was not provided in the request. For example, `legal_name_required` or `representatives_0_first_name_required`. The field can be `null`, contain empty strings, or contain white spaces.

You can simulate different failure scenarios for sub-entity onboarding in the sandbox environment as follows:

Providing specific values in the legal_name field of your onboarding request triggers different outcomes for verification checks and the sub-entity's payment capabilities.

Note

If you provide any other value, such as a company name, in the legal_name field, this triggers positive VMSS and MATCH checks, and enables payment capabilities.

You can provide the following scenarios in the legal_name field for the specified check and capabilities outcomes:

Scenario	Check outcome	Capabilities outcome
`simulator_match_fail` `simulator_vmss_fail`	Both the VMSS and the MATCH checks fail.	Remain disabled
`simulator_vmss_fail`	The VMSS check fails, but the MATCH check passes.	Remain disabled
`simulator_match_fail`	The VMSS check passes, but the MATCH check fails.	Remain disabled

Providing specific values in the legal_name or first_name field of your onboarding request triggers different outcomes for verification checks and the sub-entity's payment and payout capabilities.

Note

If you provide any other value, such as a company name, in the legal_name field, this triggers trigger positive VMSS and MATCH checks, and enables payment and payout capabilities.

For company sub-entities, you can provide the following scenarios in the legal_name field for the specified check and capabilities outcomes:

Scenario	Check outcome	Capabilities outcome
`simulator_full_dd_fail_verification_failed`	The full due diligence check fails.	Payments and payouts remain disabled.
`simulator_full_dd_fail_declined`	Due diligence checks fail, and the sub-entity status changes to `rejected`.	Payments and payouts remain disabled.
`simulator_pending_status`	The sub-entity status changes to `pending`.	Payments and payouts remain disabled.

For sole trader sub-entities, you can provide the following scenarios in the first_name field for the specified check and capabilities outcomes:

Scenario	Check outcome	Capabilities outcome
`simulator_full_dd_fail_invalid_document`	The full due diligence checks fail.	Payments and payouts remain disabled.
`simulator_full_dd_fail_declined`	The due diligence checks fail, and the sub-entity status changes to `rejected`.	Payments and payouts remain disabled.

Add supporting documents

For Full accounts, add supporting documents for sub-entity verification.

Onboard a sub-entity using the API

Information

How it works

Note

Before you begin