Sub-entity status

Last updated: December 24, 2025

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:

You can also view your sub-entity's status in the Dashboard, by following these steps:

Sign in to the Dashboard.
Go to Payments > Processing > Sub-entities.
Find the required sub-entity in the list. You can use the search bar to search by the sub-entity's name, reference, or ID.
Check the status of the sub-entity in the Status column.

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:

Pending
Requirements due (ACTION REQUIRED on the Dashboard)
Active
Rejected

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
PENDING – in the Dashboard

Information

The outcome of the verification checks may affect the sub-entity's 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
ACTION REQUIRED – in the Dashboard

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 either using the Dashboard or the Platforms API.

To check the reason in the Dashboard:

Sign in to the Dashboard.
Go to Payments > Processing > Sub-entities.
Find the required sub-entity in the list. You can use the search bar to search by the sub-entity's name, reference, or ID. Alternatively, use the search filter to filter all sub-entities with the Action required status.
Select the sub-entity. The Sub-entity details page displays. The banner at the start of the page highlights the reasons for the Action required status and the actions you need to take.

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
ACTIVE – in the Dashboard

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

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

Note

Updating a sub-entity information after verification completes, requires us to run a new verification. During this process, the sub-entity's status resets to pending.

If the sub-entity fails verification checks, it's status displays as:

rejected – in API responses and webhooks
REJECTED – in the Dashboard


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

The sub-entity cannot process payments or payouts.

The sub-entity will not be able to resume onboarding. To challenge the decision, contact your account manager.

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

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

Pending

Information

Requirements due

Response examples

Active

Note

Rejected

Related topics

Update a sub-entity

Handle webhooks