Full sub-entity onboarding
This process should be followed for those on the full
account type for our Integrated Platforms solution. We have another page for lite 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
- Add supporting documentation
- Retrieve a sub-entity
- Handle due diligence notifications
- Testing
Configure your webhooks and subscribe to:
sub_entity_created
full_dd_passed
andfull_dd_failed
payouts_enabled
andpayouts_disabled
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": "cakeshop678910",3"contact_details": {4"phone": {5"number": "111222333"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"legal_name": "The Cake Shop Inc.",17"trading_name": "The Cake Shop",18"principal_address": {19"address_line1": "90 Tottenham Court Road",20"city": "London",21"zip": "W1T4TJ",22"country": "GB"23}24}25}
A successful response will include 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_wxglze3wwywujg4nna5fb7ldli",3"reference": "abc123456789101112",4"status": "requirements_due",5"capabilities": {6"payments": {7"available": true,8"enabled": false9},10"payouts": {11"available": true,12"enabled": false13},14"requirements_due": [15{16"field": "individual.date_of_birth",17"reason": "required"18},19{20"field": "individual.identification.document",21"reason": "required"22}23],24"_links": {25"self": {26"href": "https://api.sandbox.checkout.com/entities/ent_wxglze3wwywujg4nna5fb7ldli"27}28}29}30}
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": "superher01234",9"legal_name": "Super Hero Masks Inc."10},11"_links": {12"self": {13"href": "https://api.sandbox.checkout.com/workflows/events/evt_jqv4f6zedawetlilolhqun6m4m"14}15}16}
Use this endpoint to update all fields under the contact_details
, profile
, and company
objects. To get a detailed view of all required and optional fields, see our API reference.
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": "cakeshop678910",3"contact_details": {4"phone": {5"number": "111222333"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": "452349600005",17"legal_name": "The Cake Shop Inc.",18"trading_name": "The Cake Shop",19"principal_address": {20"address_line1": "90 Tottenham Court Road",21"city": "London",22"zip": "W1T4TJ",23"country": "GB"24},25"registered_address": {26"address_line1": "90 Tottenham Court Road",27"city": "London",28"zip": "W1T4TJ",29"country": "GB"30},31"representatives": [32{33"first_name": "Chrisi",34"last_name": "Webster",35"address": {36"address_line1": "123 ABC Close",37"city": "London",38"zip": "E1 5DP",39"country": "GB"40},41"date_of_birth": {42"day": 5,43"month": 6,44"year": 199545},46"identification": {47"document": {48"type": "Passport",49"front": "file_jxaps37jnfaupfu6bsei7rj5iu",50"back": "file_zn6v47bgphjuljjvhlpk7dnpby"51}52}53}54]55}56}
If the request was successful, you will receive 200 - Sub-entity updated successfully
.
1{2"id": "ent_wxglze3wwywujg4nna5fb7ldli",3"reference": "superhero1234",4"status": "pending",5"capabilities": {6"payments": {7"available": true,8"enabled": false9},10"payouts": {11"available": true,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}
Use our Files API to upload:
- Identification for know your customer (KYC) due diligence checks
- Documentation to verify a company for know your business (KYB) checks
The Files API returns an id
that represents that file. Use this to add supporting documentation while onboarding a sub-entity, or when you update the sub-entity.
All you need to include is the identification.document
object in your request, with the following pieces of information:
- Type: Read more about what types are accepted.
- Front: Required for all identification types. This should be the
id
returned when you uploaded the file - Back: Only required if the type is not a passport. This should be the
id
returned when you uploaded the file
1{2"individual": {3"first_name": "Daniel",4"last_name": "Yubi",5"trading_name": "Daniel's Donuts",6"national_tax_id": "1234567",7"registered_address": {8"address_line1": "90 Tottenham Court Road",9"city": "London",10"zip": "W1T4TJ",11"country": "GB"12},13"date_of_birth": {14"day": 5,15"month": 6,16"year": 199517},18"identification": {19"document": {20"type": "passport",21"front": "file_jxaps37jnfaupfu6bsei7rj5iu"22}23}24}25}
Note
Providing an identity document is the last step before triggering due diligence checks. To prevent multiple due diligence checks, please add all representatives before uploading their identification documents.
Note
Only needed for sub-entities who have been onboarded as a company.
All you need to include is the company.document
object in your request, with the following pieces of information:
- File ID: This should be the
id
returned when you uploaded the file - Type: The type of document you are providing. For example, certificate of incorporation
1{2"company": {3"business_registration_number": "452349600005",4"legal_name": "The Cake Shop Inc.",5"trading_name": "The Cake Shop",6"principal_address": {7"address_line1": "90 Tottenham Court Road",8"city": "London",9"zip": "W1T4TJ",10"country": "GB"11},12"document": {13"file_id": "file_6lbss42ezvoufcb2beo76rvwly",14"type": "Certificate of incorporation"15}16}17}
To get a detailed view of all required and optional fields, see our API reference.
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": "danielsdonuts0123456",4"status": "active",5"capabilities": {6"payments": {7"available": true,8"enabled": true9},10"payouts": {11"available": true,12"enabled": false13}14},15"profile": {16"default_holding_currency": "GBP",17"urls": ["https://www.daniels-donuts.com"],18"mccs": ["5814"]19},20"individual": {21"first_name": "Daniel",22"last_name": "Yubi",23"trading_name": "Daniel's Donuts",24"legal_name": "Daniel Yubi",25"national_tax_id": "1234567",26"registered_address": {27"address_line1": "90 Tottenham Court Road",28"city": "London",29"zip": "W1T4TJ",30"country": "GB"31}32},33"contact_details": {34"phone": {35"number": "2345678910"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 notification. You should expect to receive the following event types:
full_dd_passed
/full_dd_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.
Information
We've described the different webhook notifications on our webhook event type page.
1{2"id": "evt_htielsmgcwgejgqaunl4yb2pou",3"type": "full_dd_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": "cakeshop123456789101112",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, we will enable the sub-entity’s payments and payouts capabilities. You should expect to receive the payments_enabled
and payout_enabled
event types.
We will re-trigger due diligence checks if any of the required information is later updated. If any subsequent checks fail and you receive the full_dd_failed
notification, this will be followed by payments_disabled
and payouts_disabled
webhook notifications.
Information
We've described the different webhook notifications on our webhook event type page.
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": "cakeshop123456789101112",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}
Information
We will re-trigger due diligence checks if any of the required information is later updated. If any subsequent checks fail and you receive the vmss_failed
and / or match_failed
notification, this will be followed by payments_disabled
.
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
or first_name
field of your onboarding request. This will trigger specific outcomes regarding KYC and KYB, as well as the payment and payout 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 and payout capabilities. The simulator only accepts fail triggers.
For company sub-entities, update the legal_name
field.
Trigger to be added in legal_name | Due diligence checks | Payment and payout capabilities |
---|---|---|
| Full DD fail. | Both remain disabled. |
| Due diligence checks have failed, so sub-entity is in the | Both remain disabled. |
| Check in | Both remain disabled. |
For sole trader sub-entities, update the first_name
field.
Trigger to be added in first_name | Due diligence checks | Payment and payout capabilities |
---|---|---|
| Full DD fail. | Both remain disabled. |
| Due diligence checks have failed, so sub-entity is in the | Both remain disabled. |