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 and full_dd_failed
payouts_enabled and payouts_disabled
payments_enabled and payments_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}


1{
2  "reference": "cakeshop0123456",
3  "contact_details": {
4    "phone": {
5      "number": "2345678910"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.daniels-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Daniel",
17    "last_name": "Yubi",
18    "trading_name": "Daniel's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "90 Tottenham Court Road",
22      "city": "London",
23      "zip": "W1T4TJ",
24      "country": "GB"
25    }
26  }
27}

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": false
9    },
10    "payouts": {
11      "available": true,
12      "enabled": false
13    },
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}

The reference you provide must be an alphanumeric value and must be unique across all of your sub-entities. If you receive a 409 response, you are trying to onboard a sub-entity with a reference that has already been used. Try again with a different reference.


1{
2  "_links": {
3    "self": {
4      "href": "https://api.sandbox.checkout.com/accounts/entities/ent_lcvk7ay5zcglzvda6n7o5ws2hq"
5    }
6  }
7}

When you receive a 422, please check the API request to make sure you've included all of the required values. You can see our API reference for a full overview.


1{
2  "request_id": "0HM72UMS6H3CT:00000001",
3  "error_type": "invalid_request",
4  "error_codes": ["reference_required"]
5}

Name	Description
`profile_mccs_invalid_for_processing_scope`	The MCCs provided for the sub-entity are outside the processing scope of its platform.
`profile_default_holding_currency_invalid_for_currency_scope`	The default holding currency provided for the sub-entity is outside the currency scope of its platform.
`principal_address_country_invalid_for_processing_scope`	The principal address country provided for the sub-entity is outside the processing scope of its platform.
`client_entity_cannot_onboard_subentities`	The platform is not permitted to onboard new sub-entities.
`sub_entity_invalid`	Internal validation error. Please contact us if you receive this.
`company_or_individual_required`	The company or individual object must be supplied in your request.
`<field_name>_invalid` For example, `legal_name_invalid`, or `profile_urls_0_invalid`.	The specified field does not match the validation policies for minimum or maximum length, or formatting. The company or individual object must be supplied in your request. The only two exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`, which have different causes. See the two rows directly above.
`<field_name>_required` For example, `legal_name_required` or `representatives_0_first_name_required`.	The specified field is mandatory but was not provided in the request. For example, the field is `null`, contains empty strings, or contains white spaces.

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": 1995
45        },
46        "identification": {
47          "document": {
48            "type": "Passport",
49            "front": "file_jxaps37jnfaupfu6bsei7rj5iu",
50            "back": "file_zn6v47bgphjuljjvhlpk7dnpby"
51          }
52        }
53      }
54    ]
55  }
56}


1{
2  "reference": "cakeshop0123456",
3  "contact_details": {
4    "phone": {
5      "number": "2345678910"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.daniels-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Daniel",
17    "last_name": "Yubi",
18    "trading_name": "Daniel's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "90 Tottenham Court Road",
22      "city": "London",
23      "zip": "W1T4TJ",
24      "country": "GB"
25    },
26    "date_of_birth": {
27      "day": 5,
28      "month": 6,
29      "year": 1995
30    },
31    "identification": {
32      "document": {
33        "type": "Passport",
34        "front": "file_jxaps37jnfaupfu6bsei7rj5iu"
35      }
36    }
37  }
38}

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": false
9    },
10    "payouts": {
11      "available": true,
12      "enabled": false
13    },
14    "requirements_due": [],
15    "_links": {
16      "self": {
17        "href": "https://api.sandbox.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
18      }
19    }
20  }
21}

In the error_codes object, we will let you know what data was invalid.


1{
2  "request_id": "0HM1I9VJUDPHV:00000002",
3  "error_type": "invalid_request",
4  "error_codes": [
5    "profile_mccs_invalid_for_processing_scope",
6    "principal_address_country_invalid_for_processing_scope"
7  ]
8}

Name	Description
`profile_mccs_invalid_for_processing_scope`	The MCCs provided for the sub-entity are outside the processing scope of its platform.
`principal_address_country_invalid_for_processing_scope`	The principal address country provided for the sub-entity is outside the processing scope of its platform.
`sub_entity_invalid`	Internal validation error. Please contact us if you receive this.
`existing_sub_entity_type_invalid`	The specified sub-entity type is invalid. This occurs when the company type is used in an individual request, and vice versa.
`company_or_individual_required`	The company or individual object must be supplied in your request.
`<field_name>_invalid` For example, `legal_name_invalid`, or `profile_urls_0_invalid`.	The specified field does not match the validation policies for minimum or maximum length, or formatting. The company or individual object must be supplied in your request. The only two exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`, which have different causes. See the two rows directly above.
`<field_name>_required` For example, `legal_name_required` or `representatives_0_first_name_required`.	The specified field is mandatory but was not provided in the request. For example, the field is `null`, contains empty strings, or contains white spaces.

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": 1995
17    },
18    "identification": {
19      "document": {
20        "type": "passport",
21        "front": "file_jxaps37jnfaupfu6bsei7rj5iu"
22      }
23    }
24  }
25}


1{
2  "representatives": [
3    {
4      "first_name": "Chrisi",
5      "last_name": "Webster",
6      "address": {
7        "address_line1": "123 ABC Close",
8        "city": "London",
9        "zip": "E1 5DP",
10        "country": "GB"
11      },
12      "date_of_birth": {
13        "day": 5,
14        "month": 6,
15        "year": 1995
16      },
17      "identification": {
18        "document": {
19          "type": "passport",
20          "front": "file_jxaps37jnfaupfu6bsei7rj5iu"
21        }
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": true
9    },
10    "payouts": {
11      "available": true,
12      "enabled": false
13    }
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}

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.

Store this information, as we use it in the next step to upload identity documents.


1{
2  "id": "ent_nofjig36ypra6236f4tfm5bvui",
3  "reference": "cakeshop678910",
4  "status": "pending",
5  "capabilities": {
6    "payments": {
7      "enabled": false
8    },
9    "payouts": {
10      "enabled": false
11    }
12  },
13  "profile": {
14    "default_holding_currency": "GBP",
15    "urls": ["https://www.thecakeshop.com"],
16    "mccs": ["5814"]
17  },
18  "company": {
19    "legal_name": "The Cake Shop Inc.",
20    "trading_name": "The Cake Shop",
21    "principal_address": {
22      "address_line1": "90 Tottenham Court Road",
23      "city": "London",
24      "zip": "W1T4TJ",
25      "country": "GB"
26    },
27    "representatives": []
28  },
29  "contact_details": {
30    "phone": {
31      "number": "111222333"
32    },
33    "email_addresses": {
34      "primary": "[email protected]"
35    }
36  },
37  "instruments": [],
38  "requirements_due": [],
39  "_links": {
40    "self": {
41      "href": "https://api.sandbox.checkout.com/accounts/entities/ent_nofjig36ypra6236f4tfm5bvui"
42    }
43  }
44}

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}


1{
2  "id": "evt_u2bs7wtytscexfrbz47qmgp62i",
3  "type": "full_dd_failed",
4  "version": "1.0.0",
5  "created_on": "2021-03-22T12:04:44.5996515Z",
6  "data": {
7    "reason_codes": ["declined"],
8    "sub_entity_id": "ent_3dgnkienrssoudk62llqqvj6qu",
9    "reference": "l7WtKSkVK8VxM3o",
10    "legal_name": "Smoke simulator_match_fail Company"
11  },
12  "_links": {
13    "self": {
14      "href": "https://api.sandbox.checkout.com/workflows/events/evt_u2bs7wtytscexfrbz47qmgp62i"
15    }
16  }
17}

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}


1{
2  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3  "type": "payouts_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
`simulator_full_dd_fail_verification_failed`	Full DD fail.	Both remain disabled.
`simulator_full_dd_fail_declined`	Due diligence checks have failed, so sub-entity is in the `Rejected` state.	Both remain disabled.
`simulator_pending_status`	Check in `Pending` state.	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
`simulator_full_dd_fail_invalid_document`	Full DD fail.	Both remain disabled.
`simulator_full_dd_fail_declined`	Due diligence checks have failed, so sub-entity is in the `Rejected` state.	Both remain disabled.

Full sub-entity onboarding

Before you begin

Onboard a sub-entity

Request examples

Response examples

Webhook notification example

Update a sub-entity

Request examples

Response examples

Add supporting documentation

Identification

Note

Company verification

Note

Retrieve a sub-entity

Response examples

Handle due diligence notifications

Due diligence webhook example

Information

Payment and payout webhook examples

Information

Information

Testing

Company sub-entities

Sole trader sub-entities

Related topics

Upload a file

Manage bank accounts

Manage card details

Due diligence checks