Sub-entity status
Beta

Last updated: March 25, 2026

Through its lifecycle, a sub-entity can transition through different statuses that define its payment capabilities.

You can check the status of a sub-entity in the responses of the following API calls:

If you configure your webhook server, you're notified of the status update through the Status changed webhook.

Through its lifecycle, your sub-entity can have one of the following statuses:

Draft
Pending
Requirements due
Active
Restricted
Rejected
Inactive

If the sub-entity has begun but not submitted their onboarding application, their status displays as draft. This means that the onboarding application is incomplete and verification checks haven't been triggered.

We start verification checks only after we have all of the required information. Once we start the verification process, the sub-entity's status displays as pending in API responses and webhooks.

Information

The outcome of the verification checks may affect the sub-entity's payment capabilities.

If we need additional information before we can start verification checks, the sub-entity's status displays as requirements_due in API responses and webhooks.

We also send the Status changed and Full DD failed webhooks. You can then take action to correct this and run the checks again.

You can check the reason for this status using the Platforms API.

To check the reason using the API, call the Get entity details endpoint.


1{
2  "id": "ent_sea5kqczeqvnznx5lqsbbsnlq4",
3  "reference": "HEjzSLlfjLuvx5l",
4  "status": "requirements_due",
5  "instruments": [],
6  "requirements_due": [
7    {
8      "field": "company.document",
9      "reason": "required"
10    },
11    {
12      "field": "company.financial_details.documents.bank_statement",
13      "reason": "required"
14    },
15    {
16      "field": "company.representatives[0].identification.document",
17      "reason": "document_expired"
18    }
19
20  ],
21  "contact_details": {
22    "phone": {
23      "number": "1234 567890"
24    }
25  },
26  "profile": {
27    "default_holding_currency": "GBP",
28    "urls": ["https://www.exampleurl.com"],
29    "mccs": ["5551"]
30  },
31  "company": {
32    "business_registration_number": "12345678",
33    "legal_name": "Acme Corporation LTD",
34    "trading_name": "Acme Corporation",
35    "principal_address": {
36      "address_line1": "111 Example Road",
37      "city": "London",
38      "zip": "SW1A 1AA",
39      "country": "GB"
40    },
41    "registered_address": {
42      "address_line1": "111 Example Road",
43      "city": "London",
44      "zip": "SW1A 1AA",
45      "country": "GB"
46    },
47    "representatives": [
48      {
49        "id": "rep_3ipq26zsxt3n24rh2vojjkfez4",
50        "address": {
51          "address_line1": "111 Example Road",
52          "city": "London",
53          "zip": "SW1A 1AA",
54          "country": "GB"
55        },
56        "phone": {
57          "number": "1234 567890"
58        },
59        "first_name": "Jane",
60        "last_name": "Smith",
61        "date_of_birth": {
62          "day": 5,
63          "month": 6,
64          "year": 1995
65        },
66        "place_of_birth": {
67          "country": "GB"
68        },
69        "identification": {
70          "document": {
71            "type": "passport",
72            "front": "file_a2waebevmihts7s74bie3w3nf4"
73          }
74        }
75      }
76    ]
77  },
78  "capabilities": {
79    "payments": {
80      "enabled": false,
81      "available": true
82    },
83    "payouts": {
84      "enabled": false,
85      "available": true
86    },
87    "issuing": {
88      "enabled": false,
89      "available": false
90    }
91  },
92  "_links": {
93    "self": {
94      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_sea5kqczeqvnznx5lqsbbsnlq4"
95    },
96    "schema": {
97      "href": "https://{prefix}.api.checkout.com/accounts/entities/_schema?resource_type=Entity&type=Company&schema_version=&country=GB"
98    }
99  }
100}

The response returns a requirements_due object that lists the affected fields along with the reason each field was rejected.

The following table lists the possible reasons for the requirements_due status, and describes the action you will need to take to continue the checks.

Reason	Action required
`required`	The document is required to start verification checks for the first time. Provide the document and resubmit.
`document_expired`	The document provided is expired. Upload a new identification document for the individual or representative.
`document_mismatch_submitted_address`	The address you have submitted for the representative is incorrect. Submit the correct address.
`document_mismatch_submitted_date_of_birth`	The date of birth you have submitted for the representative is incorrect. Submit the correct date of birth.
`document_mismatch_submitted_individual_name`	The first and/or last name for the representative is incorrect. Submit the correct first and last names.
`document_submitted_mismatch_ssn`	The social security number (SSN) you have submitted for the representative is incorrect. Submit the correct SSN.
`document_type_invalid`	The uploaded document is not from the supported list of documents. Upload documents that are from the list of document types shown.
`document_unreadable`	The uploaded document is not readable. Upload documents that are legible, colored, and have all four corners showing.
`document_unverifiable`	The uploaded document cannot be verified. For further assistance, request support.
`invalid_company_document`	The Certificate of Incorporation (COI) or Articles (AOA)/Memorandum of Association (MOA) document does not match the company details provided. Upload a valid company document.
`invalid_company_name`	The legal company name you have submitted does not match the company verification document. Submit a legal company name that matches the uploaded company verification document.
`ownership_data_missing`	Your submission is missing company Ultimate Beneficial Owners (UBOs). Submit details of all registered UBOs.
`unidentified_details`	The individual details, such as address or date of birth, couldn't be verified against our provider databases. Upload an identification document for the individual or representative.
`verification_failed`	The company details, such as legal name or registered address, couldn't be verified against our provider databases. Upload a new COI.

To add the missing information, you must update the sub-entity.

If the sub-entity passes verification checks, the sub-entity's status displays as active in API responses and webhooks and their payments or payouts capabilities are enabled.

Active sub-entities don't have any outstanding requirements.

Note

Updating a sub-entity's information after verification completes, requires us to run a new verification.

If the sub-entity's payment capabilities are restricted, their status displays as restricted.

The sub-entity cannot process payments or payouts.

If the sub-entity fails verification checks, it's status displays as rejected in API responses and webhooks.

The sub-entity cannot process payments or payouts.

The sub-entity will not be able to resume onboarding. To challenge the decision, request support.

If you attempt to update a rejected sub-entity via the API, you receive a 442 response with the error code status_invalid.

If the sub-entity is inactive and no longer able to process payments, their status displays as inactive in API responses and webhooks.

This status can be due to offboarding or termination of their contract with your platform.

The reason for this status is displayed in the status_reason field.

Update a sub-entity

Learn how you can update a sub-entity on your platform.

Handle webhooks

Learn about the different webhooks you receive when onboarding sub-entities.

Sub-entity status
Beta

Draft

Pending

Information

Requirements due

Response examples

Active

Note

Restricted

Rejected

Inactive

Related topics

Update a sub-entity

Handle webhooks