Submit application
Beta

Last updated: September 16, 2026

After a sub-entity's verification requirements have been collected, a sub-entity must submit its information for onboarding using the Platforms API.

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

Your account is configured to submit sub-entities for onboarding by Checkout.com.
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


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

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

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. The sub-entity must 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 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 may 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 via 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 your Checkout.com's processing scope.
`client_entity_cannot_onboard_subentities`	New sub-entities are not permitted to be onboarded.
`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 has used 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 the 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

Response examples

201 – Application submitted successfully

409 – Conflict

422 – Invalid data was sent

Possible error codes

Test your integration

Next steps

Add supporting documents