Submit application
Beta

Last updated: May 21, 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 (SaaS)
Sole trader sub-entity – US Sole Trader (SaaS)

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

Information

For a company sub-entity, you must set is_registered_company to true.


1{
2  "reference": "isv-seller-example001",
3  "submitter": {
4    "ip_address": "203.0.113.42"
5  },
6  "seller_category": "cat_retail_001",
7  "documents": {
8    "tax_verification": {
9      "type": "ein_letter",
10      "front": "file_wxglze3wwywujg4nna5fb7ldli"
11    }
12  },
13  "processing_details": {
14    "annual_processing_volume": 120000,
15    "average_transaction_value": 2000,
16    "average_order_fulfillment_time": 3,
17    "target_countries": [
18      "US"
19    ],
20    "currency": "USD"
21  },
22  "contact_details": {
23    "phone": {
24      "number": "4155678900",
25      "country_code": "US"
26    },
27    "email_addresses": {
28      "primary": "toby.arden@example.com"
29    }
30  },
31  "profile": {
32    "urls": [
33      "https://www.isv-seller-example.com"
34    ],
35    "mccs": [
36      "5551"
37    ],
38    "holding_currencies": [
39      "USD"
40    ],
41    "default_holding_currency": "USD"
42  },
43  "company": {
44    "is_registered_company": true,
45    "business_registration_number": "12-3456789",
46    "business_type": "private_corporation",
47    "legal_name": "ISV Seller Example Inc",
48    "trading_name": "ISV Seller Example",
49    "registered_address": {
50      "address_line1": "123 Main Street",
51      "city": "San Francisco",
52      "state": "CA",
53      "zip": "94105",
54      "country": "US"
55    },
56    "principal_address": {
57      "address_line1": "123 Main Street",
58      "city": "San Francisco",
59      "state": "CA",
60      "zip": "94105",
61      "country": "US"
62    },
63    "date_of_incorporation": {
64      "year": 2025,
65      "month": 10,
66      "day": 1
67    },
68    "representatives": [
69      {
70        "roles": [
71          "ubo",
72          "control_person"
73        ],
74        "ownership_percentage": 25,
75        "company_position": "ceo",
76        "individual": {
77          "first_name": "Toby",
78          "last_name": "Arden",
79          "email_address": "toby.arden@example.com",
80          "national_id_type": "ssn",
81          "national_id_number": "123456789",
82          "date_of_birth": {
83            "day": 15,
84            "month": 1,
85            "year": 1990
86          },
87          "place_of_birth": {
88            "country": "US"
89          },
90          "citizenships": [
91            {
92              "country": "US"
93            }
94          ],
95          "phone": {
96            "country_code": "US",
97            "number": "4155678901"
98          },
99          "address": {
100            "address_line1": "123 Main Street",
101            "city": "San Francisco",
102            "state": "CA",
103            "zip": "94105",
104            "country": "US"
105          }
106        }
107      },
108      {
109        "roles": [
110          "authorised_signatory"
111        ],
112        "individual": {
113          "first_name": "Alex",
114          "last_name": "Morgan",
115          "email_address": "alex.morgan@example.com",
116          "national_id_type": "ssn",
117          "national_id_number": "987654321",
118          "date_of_birth": {
119            "day": 22,
120            "month": 6,
121            "year": 1985
122          },
123          "place_of_birth": {
124            "country": "US"
125          },
126          "citizenships": [
127            {
128              "country": "US"
129            }
130          ],
131          "phone": {
132            "country_code": "US",
133            "number": "4155678902"
134          },
135          "address": {
136            "address_line1": "123 Main Street",
137            "city": "San Francisco",
138            "state": "CA",
139            "zip": "94105",
140            "country": "US"
141          }
142        }
143      }
144    ]
145  }
146}

Information

For a sole trader sub-entity, you must:

Set is_registered_company to false.
Set business_type to individual_or_sole_proprietorship.
Specify only one representative inrepresentatives, the individual themselves with their role set to ubo.


1{
2  "reference": "isv-sole-trader-example001",
3  "submitter": {
4    "ip_address": "203.0.113.42"
5  },
6  "seller_category": "cat_retail_001",
7  "documents": {
8    "tax_verification": {
9      "type": "ein_letter",
10      "front": "file_wxglze3wwywujg4nna5fb7ldli"
11    }
12  },
13  "processing_details": {
14    "annual_processing_volume": 1000,
15    "average_transaction_value": 2000,
16    "average_order_fulfillment_time": 3,
17    "target_countries": [
18      "US"
19    ],
20    "currency": "USD"
21  },
22  "contact_details": {
23    "phone": {
24      "number": "4155678900",
25      "country_code": "US"
26    },
27    "email_addresses": {
28      "primary": "hannah.bret@example.com"
29    }
30  },
31  "profile": {
32    "urls": [
33      "https://www.isv-sole-trader-example.com"
34    ],
35    "mccs": [
36      "5551"
37    ],
38    "holding_currencies": [
39      "USD"
40    ],
41    "default_holding_currency": "USD"
42  },
43  "company": {
44    "is_registered_company": false,
45    "business_type": "individual_or_sole_proprietorship",
46    "trading_name": "Hannah's Goods",
47    "date_of_incorporation": {
48      "year": 2025,
49      "month": 10,
50      "day": 1
51    },
52    "principal_address": {
53      "address_line1": "123 Main Street",
54      "city": "San Francisco",
55      "state": "CA",
56      "zip": "94105",
57      "country": "US"
58    },
59    "representatives": [
60      {
61        "roles": [
62          "ubo"
63        ],
64        "ownership_percentage": 100,
65        "individual": {
66          "first_name": "Hannah",
67          "last_name": "Bret",
68          "email_address": "hannah.bret@example.com",
69          "national_id_type": "ssn",
70          "national_id_number": "123456789",
71          "date_of_birth": {
72            "day": 15,
73            "month": 1,
74            "year": 1990
75          },
76          "place_of_birth": {
77            "country": "US"
78          },
79          "citizenships": [
80            {
81              "country": "US"
82            }
83          ],
84          "phone": {
85            "country_code": "US",
86            "number": "4155678901"
87          },
88          "address": {
89            "address_line1": "123 Main Street",
90            "city": "San Francisco",
91            "state": "CA",
92            "zip": "94105",
93            "country": "US"
94          }
95        },
96        "documents": {
97          "identity_verification": {
98            "type": "driving_license",
99            "front": "file_wxglze3wwywujg4nna5fb7ldli",
100            "back": "file_2bxglze3wwywujg4nna5fb7ldl"
101          }
102        }
103      }
104    ]
105  }
106}

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 test your integration by simulating different onboarding scenarios in the sandbox environment by using the Onboarding simulator API. For more information, see Simulate onboarding scenarios.

Add supporting documents

Add supporting documents for sub-entity verification.

Submit application
Beta

Before you start

Onboard a sub-entity

Information

Information

Request examples

Information

Information

Response examples

201 – Application submitted successfully

409 – Conflict

422 – Invalid data was sent

Possible error codes

Test your integration

Next steps

Add supporting documents