Submit application
Beta

Last updated: March 25, 2026

After you've collected the verification requirements from your sub-entities, you must submit their information for onboarding using the Platforms API.

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 your webhook server and subscribed to the relevant events.

Call the Onboard an entity endpoint.

In the request body, provide all the required fields applicable to the schema for your sub-entity type:

Company sub-entity – US Company - Full (3.0)
Sole trader sub-entity – US Sole Trader - Full (3.0)

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's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/accounts/entities


1{
2    "reference": "ref-123456",
3    "seller_category": "Gold",
4    "profile": {
5        "urls": [
6            "https://www.theonlineretailer.com"
7        ],
8        "mccs": [
9            "5551"
10        ]
11    },
12    "contact_details": {
13        "phone": {
14            "number": "9934567890123",
15            "country_code": "US"
16        },
17        "email_addresses": {
18            "primary": "theonlineretailer@example.com"
19        }
20    },
21    "company": {
22        "business_registration_number": "123456789",
23        "business_type": "private_corporation",
24        "legal_name": "The Online Retailer",
25        "trading_name": "The Online Retailer",
26        "principal_address": {
27            "address_line1": "123 Anywhere St.",
28            "city": "Anytown",
29            "zip": "123456",
30            "state": "AL",
31            "country": "US"
32        },
33        "registered_address": {
34            "address_line1": "123 Anywhere St.",
35            "city": "Anytown",
36            "zip": "123456",
37            "state": "AL",
38            "country": "US"
39        },
40        "date_of_incorporation": {
41            "month": 6,
42            "year": 1950
43        },
44        "representatives": [
45            {
46                "individual": {
47                    "first_name": "Toby",
48                    "last_name": "Arden",
49                    "address": {
50                        "address_line1": "123 Anywhere St.",
51                        "city": "Anytown",
52                        "zip": "123456",
53                        "state": "AL",
54                        "country": "US"
55                    },
56                    "date_of_birth": {
57                        "day": 5,
58                        "month": 6,
59                        "year": 1995
60                    },
61                    "phone": {
62                        "number": "2443456789",
63                        "country_code": "US"
64                    },
65                    "place_of_birth": {
66                        "country": "US"
67                    },
68                    "national_id_number": "223123123",
69                    "email_address": "toby.arden@example.com"
70                },
71                "roles": [
72                    "authorised_signatory",
73                    "control_person"
74                ],
75                "company_position": "cfo",
76
77                "documents": {
78                    "identity_verification": {
79                        "front": "file_4564675",
80                        "type": "passport"
81                    }
82                }
83            },
84            {
85                "individual": {
86                    "first_name": "Hannah",
87                    "last_name": "Bret",
88                    "address": {
89                        "address_line1": "123 Anywhere St.",
90                        "city": "Anytown",
91                        "zip": "123456",
92                        "state": "AL",
93                        "country": "US"
94                    },
95                    "date_of_birth": {
96                        "day": 5,
97                        "month": 6,
98                        "year": 1995
99                    },
100                    "phone": {
101                        "number": "2443456789",
102                        "country_code": "US"
103                    },
104                    "place_of_birth": {
105                        "country": "US"
106                    },
107                    "national_id_number": "223123123",
108                    "email_address": "hannah.bret@example.com"
109                },
110                "ownership_percentage": 30,
111                "roles": [
112                    "ubo"
113                ],
114                "documents": {
115                    "identity_verification": {
116                        "front": "file_4323554",
117                        "type": "passport"
118                    }
119                }
120            }
121        ]
122    },
123    "processing_details": {
124        "currency": "USD",
125        "annual_processing_volume": 100000,
126        "average_transaction_value": 5000,
127        "highest_transaction_value": 10000,
128        "settlement_country": "US",
129        "target_countries": [ "US", "VI" ]
130    }
131}


1{
2    "reference": "ref-123456",
3    "seller_category": "Gold",
4    "profile": {
5        "urls": [
6            "https://www.theonlineretailer.com"
7        ],
8        "mccs": [
9            "5551"
10        ]
11    },
12    "contact_details": {
13        "phone": {
14            "number": "9934567890123",
15            "country_code": "US"
16        },
17        "email_addresses": {
18            "primary": "theonlineretailer@example.com"
19        }
20    },
21    "company": {
22        "business_registration_number": "123456789",
23        "business_type": "individual_or_sole_proprietorship",
24        "legal_name": "The Online Retailer",
25        "trading_name": "The Online Retailer",
26        "principal_address": {
27            "address_line1": "123 Anywhere St.",
28            "city": "Anytown",
29            "zip": "123456",
30            "state": "AL",
31            "country": "US"
32        },
33        "registered_address": {
34            "address_line1": "123 Anywhere St.",
35            "city": "Anytown",
36            "zip": "123456",
37            "state": "AL",
38            "country": "US"
39        },
40        "date_of_incorporation": {
41            "month": 6,
42            "year": 1950
43        },
44        "representatives": [
45            {
46                "individual": {
47                    "first_name": "Hannah",
48                    "last_name": "Bret",
49                    "address": {
50                        "address_line1": "123 Anywhere St.",
51                        "city": "Anytown",
52                        "zip": "123456",
53                        "state": "AL",
54                        "country": "US"
55                    },
56                    "date_of_birth": {
57                        "day": 5,
58                        "month": 6,
59                        "year": 1995
60                    },
61                    "phone": {
62                        "number": "2443456789",
63                        "country_code": "US"
64                    },
65                    "place_of_birth": {
66                        "country": "US"
67                    },
68                    "national_id_number": "223123123",
69                    "email_address": "hannah.bret@example.com"
70                },
71                "ownership_percentage": 70,
72                "roles": [
73                    "ubo"
74                ],
75                "documents": {
76                    "identity_verification": {
77                        "front": "file_4323554",
78                        "type": "passport"
79                    }
80                }
81            }
82        ]
83    },
84    "processing_details": {
85        "currency": "USD",
86        "annual_processing_volume": 100000,
87        "average_transaction_value": 5000,
88        "highest_transaction_value": 10000,
89        "settlement_country": "US",
90        "target_countries": [ "US", "VI" ]
91    }
92}

You can receive one of the following HTTP responses:

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


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 a list of 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 Merchant Category Codes (MCC) 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 by providing specific values in the legal_name or first_name fields of your onboarding request. Each value generates a different outcome 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

Add supporting documents for sub-entity verification.

Submit application
Beta

Before you begin

Onboard a sub-entity

Information

Information

Request examples

Response examples

201 – Application submitted successfully

409 – Conflict

422 – Invalid data was sent

Possible error codes

Test your integration

Note

Company sub-entities

Sole trader sub-entities

Next steps

Add supporting documents