Onboard a sub-entity with the API

Last updated: July 26, 2023

The Accounts API uses OAuth authentication.

Your account type is determined during onboarding and depends on whether you require payment capabilities (lite), or payment and payout capabilities (full).

Lite accounts can only process payments – all funds are settled to your platform as per the frequency agreed during onboarding
Full accounts can process payments and payouts on behalf of their sub-entities – funds are paid out from your sub-entity's currency account to their bank account using our payouts solution

For visibility into the status of your sub-entity during onboarding, a status field is included in the responses to the following API calls:

If you've set up your webhook receiver, you'll be notified asynchronously of any changes to your sub-entity's status via the status_changed webhook.

We only trigger due diligence checks when we have all of the required information. Once the checks are triggered, the sub-entity's status will display as pending in API responses and webhook notifications.

Information

The outcome of the due diligence checks may affect the sub-entity's capabilities.

If we're expecting you to provide us with additional information before we trigger due diligence checks, the sub-entity's status will display as requirements_due in API responses and webhook notifications.

Information

For more information on possible verification errors and how to solve them, see the Due diligence checks page.

If you retrieve the sub-entity's details via the API, the response will also contain a requirements_due object listing the missing information.

For example, if you've created a company sub-entity without providing information on company representatives, or a registered address, you'll receive the following response:


1{
2  "id": "ent_vjmdzvijizs7o26kiuiakywvyi",
3  "reference": "tmvhWvvZfFSkJy4",
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",
16      "reason": "required"
17    },
18    {
19      "field": "company.registered_address",
20      "reason": "required"
21    }
22  ],
23  "_links": {
24    "self": {
25      "href": "https://api.checkout.com/accounts/entities/ent_vjmdzvijizs7o26kiuiakywvyi"
26    }
27  }
28}

If the sub-entity passes due diligence checks, the sub-entity's status will display as active in API responses and webhook notifications.

The sub-entity's payments or payouts capabilities will be enabled, as determined by your account type.

There are no outstanding requirements for sub-entities with this status.

Note

If you update the sub-entity's information after it has passed due diligence checks, new checks will be triggered. The sub-entity's status will be reset to pending in API responses and webhook notifications.

If the sub-entity fails due diligence checks, the sub-entity's status will display as rejected in API responses and webhook notifications.

The sub-entity's payments or payouts capabilities will not be enabled.

This decision is final and the sub-entity will not be able to resume onboarding. If you attempt to update a rejected sub-entity via the API, you'll receive a 442 response with the error code status_invalid.

Note

To challenge the decision, contact your Account Manager.

Onboard a sub-entity with the API

Select your account type

Sub-entity status

Information

Information

Note

Note