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 the Dashboard.

Configure your webhooks and subscribe to:

sub_entity_created
vmss_passed and vmss_failed
match_passed and match_failed
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": "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}


1{
2  "reference": "DONUTS12345",
3  "contact_details": {
4    "phone": {
5      "number": "7700900000"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.ali-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Ali",
17    "last_name": "Farid",
18    "trading_name": "Ali's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "123 High St.",
22      "city": "London",
23      "zip": "SW1A 1AA",
24      "country": "GB"
25    }
26  }
27}

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

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": "0HM72UMS6H39C:00000003",
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": "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}


1{
2  "reference": "DONUTS12345",
3  "contact_details": {
4    "phone": {
5      "number": "7700900000"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.alis-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Ali",
17    "last_name": "Farid",
18    "trading_name": "Ali's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "123 High St.",
22      "city": "London",
23      "zip": "SW1A 1AA",
24      "country": "GB"
25    },
26    "date_of_birth": {
27      "day": 5,
28      "month": 6,
29      "year": 1995
30    }
31  }
32}

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": false
9    },
10    "payouts": {
11      "available": false,
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.

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


1{
2  "id": "ent_nofjig36ypra6236f4tfm5bvui",
3  "reference": "CAKE12345",
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": "654 Example St.",
23      "city": "Edinburgh",
24      "zip": "EH9 2XY",
25      "country": "GB"
26    },
27    "representatives": []
28  },
29  "contact_details": {
30    "phone": {
31      "number": "7700900000"
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 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}


1{
2  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3  "type": "vmss_failed",
4  "version": "1.0.0",
5  "created_on": "2020-08-20T15:24:13.8431084Z",
6  "data": {
7    "sub_entity_id": "ent_h5qk7lfsp3ludfjxba256lduju",
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
`simulator_match_fail` `simulator_vmss_fail`	Both the VMSS and the MATCH checks fail.	Remain disabled.
`simulator_vmss_fail`	The VMSS check fails, but the MATCH check passes.	Remain disabled.
`simulator_match_fail`	The VMSS check passes, but the MATCH check fails.	Remain disabled.

Process sub-entity payments

Process payments on behalf of your sub-entities.

Lite sub-entity onboarding

Information

Before you begin

Onboard a sub-entity

Request examples

Response examples

Webhook notification example

Update a sub-entity

Note

Request examples

Response example

Retrieve a sub-entity

Response examples

Handle due diligence notifications

Due diligence webhook example

Information

Information

Payments enabled webhook example

Testing

Next steps

Process sub-entity payments