# Simulate onboarding scenarios

You can simulate different sub-entity onboarding scenarios in the sandbox environment using the Onboarding simulator API.

You can use the Onboarding simulator API to:

- [Simulate an onboarding scenario](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md#Simulate_an_onboarding_scenario)
- [Set a sub-entity to a specific status](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md#Set_a_sub-entity_to_a_specific_status)
- [Flag pending requirements for a sub-entity](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md#Flag_pending_requirements_for_a_sub-entity)

Before you start, ensure that you have [created a sub-entity](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/submit-application.md#Onboard_a_sub-entity). You can do this using the [Platforms API](https://api-reference.checkout.com/#tag/Platforms).

You must also [generate an access token](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/oauth-2-0-client-credentials.md) for the sandbox environment.

> **Note**
>
> The Onboarding simulator API is not available in the production environment.

---

## Simulate an onboarding scenario

You can simulate one of the following onboarding scenarios for a sub-entity.

> **Information**
>
> You can also see the full list of supported scenarios by calling the [List scenarios](https://api-reference.checkout.com/#tag/Onboarding-Simulator/paths/~1simulate~1scenarios/get) endpoint. For more information, see [List all scenarios](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md#List_all_scenarios).

| Scenario name and ID | Description |
| --- | --- |
| Happy Path <br><br><br>ID: `happy_path` | Simulates a successful onboarding where the sub-entity is verified without any additional checks.<br><br>- The sub-entity status changes to `active`<br>- No pending requirements in the `requirements_due` array |
| Missing Data <br><br><br>ID: `requirements_due_missing_data` | Simulates an onboarding flow where the sub-entity cannot be verified due to incomplete or missing information.<br><br>- The sub-entity status changes to `requirements_due`<br>- The `requirements_due` array includes the following fields:<br>- `company.legal_name`<br>- `company.business_registration_number`<br>- `contact_details.phone.number`<br>- `contact_details.email_addresses.primary` |
| Document Verification Required <br><br><br>ID: `requirements_due_documents` | Simulates an onboarding flow where the sub-entity cannot be verified and additional supporting documents are required.<br><br>- The sub-entity status changes to `requirements_due`<br>- The `requirements_due` array includes the following fields:<br>- `documents.company_verification`<br>- `documents.identity_verification`<br>- `documents.proof_of_principal_address` |
| Identity Verification Required<br><br><br>ID: `requirements_due_identity` | Simulates an onboarding flow where the sub-entity cannot be verified and additional identity information is required.<br><br>- The sub-entity status changes to `requirements_due`<br>- The `requirements_due` array includes the following fields:<br>- `company.representatives.individual.first_name`<br>- `company.representatives.individual.last_name`<br>- `company.representatives.individual.date_of_birth` |
| Address Verification Required <br><br><br>ID: `requirements_due_address` | Simulates an onboarding flow where the sub-entity cannot be verified and additional address details are required.<br><br>- The sub-entity status changes to `requirements_due`<br>- The `requirements_due` array includes the following fields:<br>- `company.principal_address.address_line1`<br>- `company.principal_address.city`<br>- `company.principal_address.country`<br>- `company.principal_address.zip` |
| Processing Details Required <br><br><br>ID: `requirements_due_processing` | Simulates an onboarding flow where the sub-entity cannot be verified and additional processing details are required.<br><br>- The sub-entity status changes to `requirements_due`<br>- The `requirements_due` array includes the following fields:<br>- `company.processing_details.annual_processing_volume`<br>- `company.processing_details.average_transaction_value`<br>- `company.processing_details.currency` |
| Entity Rejected <br><br><br>ID: `entity_rejected` | Simulates an onboarding flow where the sub-entity fails verification and is rejected.<br><br>- The sub-entity status changes to `rejected`<br>- The `requirements_due` array contains no pending requirements |
| Entity Restricted <br><br><br>ID: `entity_restricted` | Simulates an onboarding flow where the sub-entity is restricted after verification.<br><br>- The sub-entity status changes to `restricted`<br>- The `requirements_due` array contains no pending requirements |
| Entity Deactivated <br><br><br>ID: `entity_inactive` | Simulates an onboarding flow where the sub-entity is deactivated.<br><br>- The sub-entity status changes to `inactive`<br>- The `requirements_due` array contains no pending requirements |
| Enable Payments and Payouts <br><br><br>ID: `enable_payments_and_payouts` | Simulates an onboarding flow where an active sub-entity's payment and payout capabilities are enabled.<br><br>- The sub-entity status remains unchanged<br>- The `requirements_due` array contains no pending requirements |
| Disable Payments and Payouts <br><br><br>ID: `disable_payments_and_payouts` | Simulates an onboarding flow where an active sub-entity's payment and payout capabilities are disabled.<br><br>- The sub-entity status remains unchanged<br>- The `requirements_due` array contains no pending requirements |
| Make Payments and Payouts Available <br><br><br>ID: `make_payments_and_payouts_available` | Simulates an onboarding flow where the payment and payout capabilities on the sub-entity's parent entity profile are set to available. This is done before enabling the capabilities of the sub-entity.<br><br>- The sub-entity status remains unchanged<br>- The `requirements_due` array contains no pending requirements |

To simulate an onboarding scenario, call the [Run scenario](https://api-reference.checkout.com/#tag/Onboarding-Simulator/paths/~1simulate~1entities~1%7BentityId%7D~1scenarios~1%7BscenarioId%7D/post) endpoint in the sandbox environment, and provide the following path parameters:

- Sub-entity ID as the `{entityId}` path parameter
- Scenario ID as the `{scenarioId}` path parameter

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox environment, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/accounts/simulate/entities/{entityId}/scenarios/{scenarioId}`

### Response examples

You can receive one of the following HTTP responses:

**200 – OK**

```json

{
  "entity_id": "ent_abc123",
  "scenario_id": "happy_path",
  "scenario_name": "Happy Path",
  "previous_status": "Draft",
  "current_status": "Active",
  "requirements_due": []
}

```

A successful response returns:

- `scenario_name` field – The scenario name.
- `previous_status` field – The previous status of the sub-entity.
- `current_status` field – The current status of the sub-entity.
- `requirements_due` array – The list of pending requirements for sub-entity verification.

**404 – scenario_not_found**

The scenario you specified was not found. Ensure that you provide the correct `scenario_id`.

**422 – entity_not_found**

The `entityId` you provided does not exist. Ensure that you provide the correct entity ID.

---

## Set a sub-entity to a specific status

You can manually set a sub-entity to a specific [status](https://www.checkout.com/docs/platforms/for-saas/manage-sub-entities/sub-entity-status.md) to simulate status transitions.

Call the [Set entity status](https://api-reference.checkout.com/#tag/Onboarding-Simulator/paths/~1simulate~1entities~1%7BentityId%7D~1status/post) endpoint in the sandbox environment, and provide the sub-entity ID as the `{entityId}` path parameter.

In the request body, set the `status` field to the specific value you want to assign to the sub-entity, which is one of:

- `draft`
- `requirements_due`
- `pending`
- `active`
- `restricted`
- `rejected`
- `inactive`

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox environment, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/accounts/simulate/entities/{entityId}/status`

### Request example

```json

{ "status": "active" }

```

### Response examples

You can receive one of the following HTTP responses:

**200 – OK**

```json

{
  "entity_id": "ent_abc123",
  "previous_status": "Draft",
  "current_status": "Active"
}

```

A successful response returns:

- `previous_status` field – The previous status of the sub-entity.
- `current_status` field – The current status of the sub-entity.

**400 – invalid_status**

The status value you provided was not recognized. Ensure that you provide a correct status value.

**404 – entity_not_found**

The `entityId` you provided does not exist. Ensure that you provide the correct entity ID.

---

## Flag pending requirements for a sub-entity

You can set a sub-entity to the `requirements_due` status and explicitly flag the specific fields that must be provided. This allows you to simulate onboarding flows where sub-entities can't be verified and additional information must be provided.

Call the [Set requirements due](https://api-reference.checkout.com/#tag/Onboarding-Simulator/paths/~1simulate~1entities~1%7BentityId%7D~1requirements-due/post) endpoint in the sandbox environment, and provide the sub-entity ID as the `{entityId}` path parameter.

In the request body, provide the list of all pending fields you want to flag in the `fields` array. Each field must be a valid value from the [List of available requirements](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md#List_all_available_requirements).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox environment, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/accounts/simulate/entities/{entityId}/requirements-due`

### Request example

```json

{
  "fields": [
    "company.legal_name",
    "company.business_registration_number"
  ]
}

```

### Response examples

You can receive one of the following HTTP responses:

**200 – OK**

```json

{
  "entity_id": "ent_abc123",
  "previous_status": "Active",
  "current_status": "RequirementsDue",
  "requirements_due": [
    "company.legal_name",
    "company.business_registration_number"
  ]
}

```

A successful response returns:

- `previous_status` field – The previous status of the sub-entity.
- `current_status` field – The current status of the sub-entity.
- `requirements_due` array – The list of pending requirements for sub-entity verification.

**400 – fields_required**

The `fields` array is empty or missing. Ensure that you include a `fields` array with the required list of fields.

**400 – unknown_fields**

One or more fields in the `fields` array are not valid. For the full list of valid fields you can include in this array, see [List of available requirements](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md#List_all_available_requirements).

**404 – entity_not_found**

The `entityId` you provided does not exist. Make sure you provide the correct sub-entity ID.

---

## List all available requirements

You can view the full list of all available requirements that can be used for testing the different onboarding scenarios by calling the [List available requirements](https://api-reference.checkout.com/#tag/Onboarding-Simulator/paths/~1simulate~1requirements-due/get) endpoint in the sandbox environment.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox environment, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/accounts/simulate/requirements-due`

### Response example

A successful response returns the full list of all the valid fields that can be used for testing different scenarios.

```json

[
    { "field": "company.additional_trading_names", "type": "array" },
    { "field": "company.business_registration_number", "type": "string" },
    { "field": "company.business_type", "type": "string" },
    { "field": "company.date_of_incorporation", "type": "object" },
    { "field": "company.legal_name", "type": "string" },
    { "field": "company.principal_address", "type": "object" },
    { "field": "company.principal_address.address_line1", "type": "string" },
    { "field": "company.principal_address.address_line_2", "type": "string" },
    { "field": "company.principal_address.city", "type": "string" },
    { "field": "company.principal_address.country", "type": "string" },
    { "field": "company.principal_address.state", "type": "string" },
    { "field": "company.principal_address.zip", "type": "string" },
    { "field": "company.processing_details", "type": "object" },
    { "field": "company.processing_details.annual_processing_volume", "type": "number" },
    { "field": "company.processing_details.average_transaction_value", "type": "number" },
    { "field": "company.processing_details.billing_descriptor", "type": "string" },
    { "field": "company.processing_details.card_transactions", "type": "object" },
    { "field": "company.processing_details.currency", "type": "string" },
    { "field": "company.processing_details.highest_transaction_value", "type": "number" },
    { "field": "company.processing_details.incorporation_jurisdiction", "type": "string" },
    { "field": "company.processing_details.payments.ach", "type": "object" },
    { "field": "company.processing_details.product_processing_catalog", "type": "object" },
    { "field": "company.processing_details.question_incorporation_jurisdiction", "type": "boolean" },
    { "field": "company.processing_details.solicit_charitable_donations", "type": "boolean" },
    { "field": "company.processing_details.target_countries", "type": "array" },
    { "field": "company.registered_address", "type": "object" },
    { "field": "company.registered_address.address_line1", "type": "string" },
    { "field": "company.registered_address.address_line_2", "type": "string" },
    { "field": "company.registered_address.city", "type": "string" },
    { "field": "company.registered_address.state", "type": "string" },
    { "field": "company.regulatory_license_expiration_date", "type": "object" },
    { "field": "company.representatives", "type": "array" },
    { "field": "company.representatives.company.legal_name", "type": "string" },
    { "field": "company.representatives.company.trading_name", "type": "string" },
    { "field": "company.representatives.company_position", "type": "string" },
    { "field": "company.representatives.documents.certified_authorised_signatory", "type": "object" },
    { "field": "company.representatives.documents.identity_verification", "type": "object" },
    { "field": "company.representatives.individual.address", "type": "object" },
    { "field": "company.representatives.individual.date_of_birth", "type": "object" },
    { "field": "company.representatives.individual.email_address", "type": "string" },
    { "field": "company.representatives.individual.first_name", "type": "string" },
    { "field": "company.representatives.individual.last_name", "type": "string" },
    { "field": "company.representatives.individual.middle_name", "type": "string" },
    { "field": "company.representatives.individual.pep_self_declaration", "type": "boolean" },
    { "field": "company.representatives.individual.place_of_birth", "type": "object" },
    { "field": "company.representatives.ownership_percentage", "type": "string" },
    { "field": "company.representatives.roles", "type": "array" },
    { "field": "company.trading_name", "type": "string" },
    { "field": "contact_details.email_addresses.administrative_owner", "type": "string" },
    { "field": "contact_details.email_addresses.invoice_emails", "type": "string" },
    { "field": "contact_details.email_addresses.pci_compliance_contact", "type": "string" },
    { "field": "contact_details.email_addresses.primary", "type": "string" },
    { "field": "contact_details.phone.country_code", "type": "string" },
    { "field": "contact_details.phone.number", "type": "string" },
    { "field": "documents.articles_of_association", "type": "object" },
    { "field": "documents.certified_authorised_signatory", "type": "object" },
    { "field": "documents.company_verification", "type": "object" },
    { "field": "documents.identity_verification", "type": "object" },
    { "field": "documents.proof_of_legality", "type": "object" },
    { "field": "documents.proof_of_principal_address", "type": "object" },
    { "field": "documents.shareholder_structure", "type": "object" },
    { "field": "documents.tax_verification", "type": "object" },
    { "field": "processing_details.financial_details", "type": "array" },
    { "field": "profile.default_holding_currency", "type": "string" },
    { "field": "profile.holding_currencies", "type": "array" },
    { "field": "profile.mccs", "type": "array" },
    { "field": "profile.urls", "type": "array" }
  ]

```

---

## List all scenarios

You can view the list of all available onboarding scenarios that you can simulate by calling the [List scenarios](https://api-reference.checkout.com/#tag/Onboarding-Simulator/paths/~1simulate~1scenarios/get) endpoint in the sandbox environment.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox environment, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/accounts/simulate/scenarios`

### Response example

A successful response returns the full list of all the available onboarding scenarios that you can simulate.

```json

[
   {
      "id":"happy_path",
      "name":"Happy Path",
      "description":"Advance entity straight to Active with no requirements due.",
      "action":"set_status",
      "status":"active",
      "requirements_due":[

      ]
   },
   {
      "id":"requirements_due_missing_data",
      "name":"Missing Data",
      "description":"Set entity to RequirementsDue with common missing data fields.",
      "action":"set_status",
      "status":"requirements_due",
      "requirements_due":[
         "company.legal_name",
         "company.business_registration_number",
         "contact_details.phone.number",
         "contact_details.email_addresses.primary"
      ]
   },
   {
      "id":"requirements_due_documents",
      "name":"Document Verification Required",
      "description":"Set entity to RequirementsDue with document verification requirements.",
      "action":"set_status",
      "status":"requirements_due",
      "requirements_due":[
         "documents.company_verification",
         "documents.identity_verification",
         "documents.proof_of_principal_address"
      ]
   },
   {
      "id":"requirements_due_identity",
      "name":"Identity Verification Required",
      "description":"Set entity to RequirementsDue with representative identity fields.",
      "action":"set_status",
      "status":"requirements_due",
      "requirements_due":[
         "company.representatives.individual.first_name",
         "company.representatives.individual.last_name",
         "company.representatives.individual.date_of_birth"
      ]
   },
   {
      "id":"requirements_due_address",
      "name":"Address Verification Required",
      "description":"Set entity to RequirementsDue with address-related fields.",
      "action":"set_status",
      "status":"requirements_due",
      "requirements_due":[
         "company.principal_address.address_line1",
         "company.principal_address.city",
         "company.principal_address.country",
         "company.principal_address.zip"
      ]
   },
   {
      "id":"requirements_due_processing",
      "name":"Processing Details Required",
      "description":"Set entity to RequirementsDue with processing detail fields.",
      "action":"set_status",
      "status":"requirements_due",
      "requirements_due":[
         "company.processing_details.annual_processing_volume",
         "company.processing_details.average_transaction_value",
         "company.processing_details.currency"
      ]
   },
   {
      "id":"pending",
      "name":"Pending",
      "description":"Reset entity to Pending status. For ISV sellers, clears requirements due on the data collection work item.",
      "action":"set_status",
      "status":"pending",
      "requirements_due":[

      ]
   },
   {
      "id":"entity_rejected",
      "name":"Entity Rejected",
      "description":"Set entity to Rejected status.",
      "action":"set_status",
      "status":"rejected",
      "requirements_due":[

      ]
   },
   {
      "id":"entity_restricted",
      "name":"Entity Restricted",
      "description":"Set entity to Restricted status.",
      "action":"set_status",
      "status":"restricted",
      "requirements_due":[

      ]
   },
   {
      "id":"entity_inactive",
      "name":"Entity Deactivated",
      "description":"Set entity to Inactive status.",
      "action":"set_status",
      "status":"inactive",
      "requirements_due":[

      ]
   },
   {
      "id":"enable_payments_and_payouts",
      "name":"Enable Payments and Payouts",
      "description":"Enable payments and payouts on an Active entity. Checks that the parent entity has these set as available.",
      "action":"enable_payments_and_payouts",
      "status":"",
      "requirements_due":[

      ]
   },
   {
      "id":"disable_payments_and_payouts",
      "name":"Disable Payments and Payouts",
      "description":"Disable payments and payouts on an Active entity.",
      "action":"disable_payments_and_payouts",
      "status":"",
      "requirements_due":[

      ]
   },
   {
      "id":"make_payments_and_payouts_available",
      "name":"Make Payments and Payouts Available",
      "description":"Set payments and payouts as available on a parent entity profile. Run this on a parent before enabling on sub-entities.",
      "action":"make_payments_and_payouts_available",
      "status":"",
      "requirements_due":[

      ]
   }
]

```