Lite sub-entity onboarding
Last updated: September 11, 2024
This process should be followed for those on the lite
account type for our Integrated Platforms solution. We have another page for full sub-entity onboarding.
On this page, we will walk through the complete onboarding of a sub-entity:
- Onboard a sub-entity
- Update a sub-entity
- Retrieve a sub-entity
- Handle due diligence notifications
- Testing
Information
Don't want to use code? You can onboard sub-entities using our friendly user interface in the Dashboard.
Configure your webhooks and subscribe to:
sub_entity_created
vmss_passed
andvmss_failed
match_passed
andmatch_failed
payments_enabled
andpayments_disabled
status_changed
To get a detailed view of all required and optional fields, see our API reference.
post
https://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}
A successful response includes a unique sub-entity id
, which you should store for future requests.
Additionally, the response has the capabilities
object, which shows you whether the sub-entity’s capabilities are enabled or not. Capabilities only get enabled once specific due diligence checks have been run and passed.
1{2"id": "ent_aotj3m5ggi2ecpfmxu4su5ctx4",3"reference": "CAKE12345",4"status": "requirements_due",5"capabilities": {6"payments": {7"available": true,8"enabled": false9},10"payouts": {11"available": false,12"enabled": false13}14},15"requirements_due": [16{17"field": "individual.date_of_birth",18"reason": "required"19}20],21"_links": {22"self": {23"href": "https://api.sandbox.checkout.com/accounts/entities/ent_aotj3m5ggi2ecpfmxu4su5ctx4"24}25}26}
Once your sub-entity has been successfully created, we will send you a sub_entity_created
webhook notification, which will look similar to:
1{2"id": "evt_jqv4f6zedawetlilolhqun6m4m",3"type": "sub_entity_created",4"timestamp": "2020-08-20T16:48:17.142+00:00",5"version": "1.0.0",6"data": {7"sub_entity_id": "ent_gavuonbau65upa75f77rar4yuu",8"reference": "CAKE12345",9"legal_name": "The Cake Shop Inc."10},11"_links": {12"self": {13"href": "https://api.sandbox.checkout.com/workflows/events/evt_jqv4f6zedawetlilolhqun6m4m"14}15}16}
You can update all fields under the contact_details
, profile
, and company
objects.
Note
When you update a sub-entity, we may conduct further due diligence checks when necessary. During these checks, your payment capabilities will remain unchanged.
put
https://api.checkout.com/accounts/entities/{id}
To get a detailed view of all required and optional fields, see our API reference.
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},26"registered_address": {27"address_line1": "123 High St.",28"city": "London",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}
If the request was successful, you will receive 200 - Sub-entity updated successfully
.
1{2"id": "ent_wxglze3wwywujg4nna5fb7ldli",3"reference": "CAKE12345",4"status": "pending",5"capabilities": {6"payments": {7"available": true,8"enabled": false9},10"payouts": {11"available": false,12"enabled": false13},14"requirements_due": [],15"_links": {16"self": {17"href": "https://api.sandbox.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"18}19}20}21}
If you need to retrieve a sub-entity's details, you can use our Get sub-entity details endpoint. Just include the id
of the sub-entity returned during the initial onboarding in your request. For example, https://api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli
.
get
https://api.checkout.com/accounts/entities/{id}
The response allows you to retrieve all data that has been provided about the sub-entity, including its capabilities, which informs you whether this sub-entity can process payments or not.
1{2"id": "ent_vv2jjkuf2gzj5tcw2x7ptua7zy",3"reference": "DONUTS12345",4"status": "active",5"capabilities": {6"payments": {7"available": true,8"enabled": true9},10"payouts": {11"available": false,12"enabled": false13}14},15"profile": {16"default_holding_currency": "GBP",17"urls": ["https://www.alis-donuts.com"],18"mccs": ["5814"]19},20"individual": {21"first_name": "Ali",22"last_name": "Farid",23"trading_name": "Ali's Donuts",24"legal_name": "Ali Farid",25"national_tax_id": "1234567",26"registered_address": {27"address_line1": "123 High St.",28"city": "London",29"zip": "SW1A 1AA",30"country": "GB"31}32},33"contact_details": {34"phone": {35"number": "7700900000"36},37"email_addresses": {38"primary": "[email protected]"39}40},41"instruments": [],42"requirements_due": [],43"_links": {44"self": {45"href": "https://api.sandbox.checkout.com/accounts/entities/ent_vv2jjkuf2gzj5tcw2x7ptua7zy"46}47}48}
Once we have conducted our due diligence checks, we will inform you of the outcome via webhook notifications. You should expect to receive the following event types:
vmss_passed
/vmss_failed
match_passed
/match_failed
Due diligence will always pass in the Sandbox environment, unless one of our legal_name
fail triggers is used for simulation.
On occasion, our team will need to manually review a sub-entity. Please see our onboarding page for more information.
The following diagram shows the possible sub-entity statuses and webhooks you may receive during the onboarding process on the lite
account type:
Information
We've described the different webhook notifications on our webhook event type page.
1{2"id": "evt_htielsmgcwgejgqaunl4yb2pou",3"type": "vmss_passed",4"version": "1.0.0",5"created_on": "2020-08-20T15:24:13.8431084Z",6"data": {7"sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",8"reference": "CAKE12345",9"legal_name": "The Cake Shop Inc."10},11"_links": {12"self": {13"href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"14}15}16}
If due diligence is passed (VMSS and Match), we will enable the sub-entity’s payments capability. You should expect to receive the payments_enabled
event type.
Information
We will re-trigger due diligence checks if legal_name
, trading_name
and profile.urls
is later updated. If any subsequent checks fail and you receive the vmss_failed
or match_failed
notification, this will be followed by a payments_disabled
webhook notification.
1{2"id": "evt_htielsmgcwgejgqaunl4yb2pou",3"type": "payments_enabled",4"version": "1.0.0",5"created_on": "2020-08-20T15:24:13.8431084Z",6"data": {7"sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",8"reference": "CAKE12345",9"legal_name": "The Cake Shop Inc."10},11"_links": {12"self": {13"href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"14}15}16}
You can simulate different scenarios when onboarding sub-entities. Similar to simulating payment scenarios using specific card numbers, you can use certain values in the legal_name
field of your onboarding request. This will trigger specific outcomes regarding card scheme screening, as well as the payment capabilities of a sub-entity.
Including a company name in the legal_name
field will trigger positive VMSS and MATCH checks, and will enable payment capabilities. The simulator only accepts fail triggers:
Trigger to be added in legal_name | Card scheme screening | Payment capabilities |
---|---|---|
| Both the VMSS and the MATCH checks fail. | Remain disabled. |
| The VMSS check fails, but the MATCH check passes. | Remain disabled. |
| The VMSS check passes, but the MATCH check fails. | Remain disabled. |