Submit application
Beta

Last updated: October 7, 2026

After you collect a sub-entity's verification requirements, submit its information for onboarding using the Platforms API.

Before submitting the application, ensure that:

Checkout.com has configured your account to submit sub-entities for onboarding.
You have received your client_id and client_secret, which you need to generate access tokens with the required scopes. For more information, see OAuth 2.0 client credentials.
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 company.principal_address.country 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

Automated Clearing House (ACH) fields are required only when ACH is enabled for your platform. Otherwise, these fields are optional and you can omit them.


1{
2  "reference": "isv-seller-example001",
3  "agreed_terms": {
4    "date": "2026-07-02T10:30:00Z",
5    "ip_address": "203.0.113.42",
6    "name": "Toby Arden",
7    "email": "toby.arden@example.com",
8    "version": "cko-platform-terms-1.0.0"
9  },
10  "seller_category": "cat_retail_001",
11  "processing_details": {
12    "annual_processing_volume": 1000,
13    "average_transaction_value": 2000,
14    "average_order_fulfillment_time": 3,
15    "target_countries": [
16      "US"
17    ],
18    "currency": "USD",
19    "payments": {
20      "ach": {
21        "annual_ach_volume": 100000,
22        "average_ach_transaction_size": 5000,
23        "estimated_monthly_credit_volume": 50000,
24        "average_credit_amount": 2500
25      }
26    }
27  },
28  "contact_details": {
29    "phone": {
30      "number": "5551234567",
31      "country_code": "US"
32    },
33    "email_addresses": {
34      "primary": "toby.arden@example.com",
35      "pci_compliance_contact": "ali.farid@example.com"
36    }
37  },
38  "profile": {
39    "urls": [
40      "https://www.example.com"
41    ],
42    "mccs": [
43      "5551"
44    ],
45    "holding_currencies": [
46      "USD"
47    ],
48    "default_holding_currency": "USD"
49  },
50  "company": {
51    "business_registration_number": "12-3456789",
52    "business_type": "private_corporation",
53    "legal_name": "The Online Retailer Inc",
54    "trading_name": "The Online Retailer",
55    "registered_address": {
56      "address_line1": "123 Main Street",
57      "city": "San Francisco",
58      "state": "CA",
59      "zip": "94105",
60      "country": "US"
61    },
62    "principal_address": {
63      "address_line1": "123 Main Street",
64      "city": "San Francisco",
65      "state": "CA",
66      "zip": "94105",
67      "country": "US"
68    },
69    "date_of_incorporation": {
70      "year": 2025,
71      "month": 10,
72      "day": 1
73    },
74    "representatives": [
75      {
76        "roles": [
77          "ubo",
78          "control_person"
79        ],
80        "ownership_percentage": 25,
81        "company_position": "ceo",
82        "individual": {
83          "first_name": "Toby",
84          "last_name": "Arden",
85          "email_address": "toby.arden@example.com",
86          "national_id_type": "ssn",
87          "national_id_number": "123456789",
88          "date_of_birth": {
89            "day": 15,
90            "month": 1,
91            "year": 1990
92          },
93          "place_of_birth": {
94            "country": "US"
95          },
96          "citizenships": [
97            {
98              "country": "US"
99            }
100          ],
101          "phone": {
102            "country_code": "US",
103            "number": "5551234568"
104          },
105          "address": {
106            "address_line1": "123 Main Street",
107            "city": "San Francisco",
108            "state": "CA",
109            "zip": "94105",
110            "country": "US"
111          }
112        }
113      },
114      {
115        "roles": [
116          "authorised_signatory"
117        ],
118        "individual": {
119          "first_name": "Jia",
120          "last_name": "Tsang",
121          "email_address": "jia.tsang@example.com",
122          "national_id_type": "ssn",
123          "national_id_number": "987654321",
124          "date_of_birth": {
125            "day": 22,
126            "month": 6,
127            "year": 1985
128          },
129          "place_of_birth": {
130            "country": "US"
131          },
132          "citizenships": [
133            {
134              "country": "US"
135            }
136          ],
137          "phone": {
138            "country_code": "US",
139            "number": "5551234569"
140          },
141          "address": {
142            "address_line1": "123 Main Street",
143            "city": "San Francisco",
144            "state": "CA",
145            "zip": "94105",
146            "country": "US"
147          }
148        }
149      }
150    ]
151  }
152}

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 in representatives, the individual themselves with their role set to ubo.


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

You can receive one of the following HTTP responses:

201 – Application submitted successfully
400 – Bad Request
401 – Unauthorized
409 – Conflict
422 – Invalid data was sent


1{
2  "id": "ent_nofjig36ypra6236f4tfm5bvui",
3  "reference": "isv-seller-example001",
4  "requirements_due": [
5    {
6      "field": "individual.identification.document",
7      "reason": "required",
8      "message": "required"
9    }
10  ],
11  "_links": {
12    "self": {
13      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_nofjig36ypra6236f4tfm5bvui"
14    }
15  }
16}

A successful response returns id field – The sub-entity ID, which you need for future requests.

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 value of up to 50 characters. 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've provided all required fields in the request.

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

If there's an issue when Checkout.com attempts to onboard a sub-entity, you can receive one of the following error codes:

Error code	Description
`profile_mccs_invalid_for_processing_scope`	The Merchant Category Codes (MCC) provided for the sub-entity are outside Checkout.com's processing scope for your platform.
`profile_default_holding_currency_invalid_for_currency_scope`	The default holding currency provided for the sub-entity is outside your platform's currency scope.
`principal_address_country_invalid_for_processing_scope`	The principal address country provided for the sub-entity is outside Checkout.com's processing scope for your platform.
`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 the request.
`sub_entity_invalid`	There was an internal validation error. Contact your account manager or request support.
`<field_name>_invalid`	The specified field 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`.
`<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`. You receive this error if the field is `null`, or contains empty strings or white spaces.

To test your integration, simulate different onboarding scenarios in the sandbox environment 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