Simulate onboarding scenarios
Beta

Last updated: May 20, 2026

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:

Before you start, ensure that you have created a sub-entity. You can do this using the Platforms API.

You must also generate an access token for the sandbox environment.

Note

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

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 endpoint. For more information, see List all scenarios.

Scenario name and ID Description

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

Happy Path

ID: happy_path

Simulates a successful onboarding where the sub-entity is verified without any additional checks.

The sub-entity status changes to active
No pending requirements in the requirements_due array

Missing Data

ID: requirements_due_missing_data

Simulates an onboarding flow where the sub-entity cannot be verified due to incomplete or missing information.

The sub-entity status changes to requirements_due
The requirements_due array includes the following fields:
- company.legal_name
- company.business_registration_number
- contact_details.phone.number
- contact_details.email_addresses.primary

Document Verification Required

ID: requirements_due_documents

Simulates an onboarding flow where the sub-entity cannot be verified and additional supporting documents are required.

The sub-entity status changes to requirements_due
The requirements_due array includes the following fields:
- documents.company_verification
- documents.identity_verification
- documents.proof_of_principal_address

Identity Verification Required

ID: requirements_due_identity

Simulates an onboarding flow where the sub-entity cannot be verified and additional identity information is required.

The sub-entity status changes to requirements_due
The requirements_due array includes the following fields:
- company.representatives.individual.first_name
- company.representatives.individual.last_name
- company.representatives.individual.date_of_birth

Address Verification Required

ID: requirements_due_address

Simulates an onboarding flow where the sub-entity cannot be verified and additional address details are required.

The sub-entity status changes to requirements_due
The requirements_due array includes the following fields:
- company.principal_address.address_line_1
- company.principal_address.city
- company.principal_address.country
- company.principal_address.zip

Processing Details Required

ID: requirements_due_processing

Simulates an onboarding flow where the sub-entity cannot be verified and additional processing details are required.

The sub-entity status changes to requirements_due
The requirements_due array includes the following fields:
- company.processing_details.annual_processing_volume
- company.processing_details.average_transaction_value
- company.processing_details.currency

Entity Rejected

ID: entity_rejected

Simulates an onboarding flow where the sub-entity fails verification and is rejected.

The sub-entity status changes to rejected
The requirements_due array contains no pending requirements

Entity Restricted

ID: entity_restricted

Simulates an onboarding flow where the sub-entity is restricted after verification.

The sub-entity status changes to restricted
The requirements_due array contains no pending requirements

Entity Deactivated

ID: entity_inactive

Simulates an onboarding flow where the sub-entity is deactivated.

The sub-entity status changes to inactive
The requirements_due array contains no pending requirements

Enable Payments and Payouts

ID: enable_payments_and_payouts

Simulates an onboarding flow where an active sub-entity's payment and payout capabilities are enabled.

The sub-entity status remains unchanged
The requirements_due array contains no pending requirements

Disable Payments and Payouts

ID: disable_payments_and_payouts

Simulates an onboarding flow where an active sub-entity's payment and payout capabilities are disabled.

The sub-entity status remains unchanged
The requirements_due array contains no pending requirements

Make Payments and Payouts Available

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 on the sub-entity.

The sub-entity status remains unchanged
The requirements_due array contains no pending requirements

To simulate an onboarding scenario, call the Run scenario 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.

post

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

You can receive one of the following HTTP responses:


1{
2  "entity_id": "ent_abc123",
3  "scenario_id": "happy_path",
4  "scenario_name": "Happy Path",
5  "previous_status": "Draft",
6  "current_status": "Active",
7  "requirements_due": []
8}

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.

You can manually set a sub-entity to a specific status to simulate status transitions.

Call the Set entity status 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.

post

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


1{ "status": "active" }

You can receive one of the following HTTP responses:


1{
2  "entity_id": "ent_abc123",
3  "previous_status": "Draft",
4  "current_status": "Active"
5}

A successful response returns:

previous_status field – The previous status of the sub-entity.
current_status field – The current status of the 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 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.

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.

post

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


1{
2  "fields": [
3    "company.legal_name",
4    "company.business_registration_number"
5  ]
6}

You can receive one of the following HTTP responses:


1{
2  "entity_id": "ent_abc123",
3  "previous_status": "Active",
4  "current_status": "RequirementsDue",
5  "requirements_due": [
6    "company.legal_name",
7    "company.business_registration_number"
8  ]
9}

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.

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

get

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

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


1[
2    { "field": "company.additional_trading_names", "type": "array" },
3    { "field": "company.business_registration_number", "type": "string" },
4    { "field": "company.business_type", "type": "string" },
5    { "field": "company.date_of_incorporation", "type": "object" },
6    { "field": "company.legal_name", "type": "string" },
7    { "field": "company.principal_address", "type": "object" },
8    { "field": "company.principal_address.address_line_1", "type": "string" },
9    { "field": "company.principal_address.address_line_2", "type": "string" },
10    { "field": "company.principal_address.city", "type": "string" },
11    { "field": "company.principal_address.country", "type": "string" },
12    { "field": "company.principal_address.state", "type": "string" },
13    { "field": "company.principal_address.zip", "type": "string" },
14    { "field": "company.processing_details", "type": "object" },
15    { "field": "company.processing_details.annual_processing_volume", "type": "number" },
16    { "field": "company.processing_details.average_transaction_value", "type": "number" },
17    { "field": "company.processing_details.billing_descriptor", "type": "string" },
18    { "field": "company.processing_details.card_transactions", "type": "object" },
19    { "field": "company.processing_details.currency", "type": "string" },
20    { "field": "company.processing_details.highest_transaction_value", "type": "number" },
21    { "field": "company.processing_details.incorporation_jurisdiction", "type": "string" },
22    { "field": "company.processing_details.payments.ach", "type": "object" },
23    { "field": "company.processing_details.product_processing_catalog", "type": "object" },
24    { "field": "company.processing_details.question_incorporation_jurisdiction", "type": "boolean" },
25    { "field": "company.processing_details.solicit_charitable_donations", "type": "boolean" },
26    { "field": "company.processing_details.target_countries", "type": "array" },
27    { "field": "company.registered_address", "type": "object" },
28    { "field": "company.registered_address.address_line_1", "type": "string" },
29    { "field": "company.registered_address.address_line_2", "type": "string" },
30    { "field": "company.registered_address.city", "type": "string" },
31    { "field": "company.registered_address.state", "type": "string" },
32    { "field": "company.regulatory_license_expiration_date", "type": "object" },
33    { "field": "company.representatives", "type": "array" },
34    { "field": "company.representatives.company.legal_name", "type": "string" },
35    { "field": "company.representatives.company.trading_name", "type": "string" },
36    { "field": "company.representatives.company_position", "type": "string" },
37    { "field": "company.representatives.documents.certified_authorised_signatory", "type": "object" },
38    { "field": "company.representatives.documents.identity_verification", "type": "object" },
39    { "field": "company.representatives.individual.address", "type": "object" },
40    { "field": "company.representatives.individual.date_of_birth", "type": "object" },
41    { "field": "company.representatives.individual.email_address", "type": "string" },
42    { "field": "company.representatives.individual.first_name", "type": "string" },
43    { "field": "company.representatives.individual.last_name", "type": "string" },
44    { "field": "company.representatives.individual.middle_name", "type": "string" },
45    { "field": "company.representatives.individual.pep_self_declaration", "type": "boolean" },
46    { "field": "company.representatives.individual.place_of_birth", "type": "object" },
47    { "field": "company.representatives.ownership_percentage", "type": "string" },
48    { "field": "company.representatives.roles", "type": "array" },
49    { "field": "company.trading_name", "type": "string" },
50    { "field": "contact_details.email_addresses.administrative_owner", "type": "string" },
51    { "field": "contact_details.email_addresses.invoice_emails", "type": "string" },
52    { "field": "contact_details.email_addresses.pci_compliance_contact", "type": "string" },
53    { "field": "contact_details.email_addresses.primary", "type": "string" },
54    { "field": "contact_details.phone.country_code", "type": "string" },
55    { "field": "contact_details.phone.number", "type": "string" },
56    { "field": "documents.articles_of_association", "type": "object" },
57    { "field": "documents.certified_authorised_signatory", "type": "object" },
58    { "field": "documents.company_verification", "type": "object" },
59    { "field": "documents.identity_verification", "type": "object" },
60    { "field": "documents.proof_of_legality", "type": "object" },
61    { "field": "documents.proof_of_principal_address", "type": "object" },
62    { "field": "documents.shareholder_structure", "type": "object" },
63    { "field": "documents.tax_verification", "type": "object" },
64    { "field": "processing_details.financial_details", "type": "array" },
65    { "field": "profile.default_holding_currency", "type": "string" },
66    { "field": "profile.holding_currencies", "type": "array" },
67    { "field": "profile.mccs", "type": "array" },
68    { "field": "profile.urls", "type": "array" }
69  ]

You can view the list of all available onboarding scenarios that you can simulate by calling the List scenarios 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.

get

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

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


1[
2   {
3      "id":"happy_path",
4      "name":"Happy Path",
5      "description":"Advance entity straight to Active with no requirements due.",
6      "action":"set_status",
7      "status":"active",
8      "requirements_due":[
9         
10      ]
11   },
12   {
13      "id":"requirements_due_missing_data",
14      "name":"Missing Data",
15      "description":"Set entity to RequirementsDue with common missing data fields.",
16      "action":"set_status",
17      "status":"requirements_due",
18      "requirements_due":[
19         "company.legal_name",
20         "company.business_registration_number",
21         "contact_details.phone.number",
22         "contact_details.email_addresses.primary"
23      ]
24   },
25   {
26      "id":"requirements_due_documents",
27      "name":"Document Verification Required",
28      "description":"Set entity to RequirementsDue with document verification requirements.",
29      "action":"set_status",
30      "status":"requirements_due",
31      "requirements_due":[
32         "documents.company_verification",
33         "documents.identity_verification",
34         "documents.proof_of_principal_address"
35      ]
36   },
37   {
38      "id":"requirements_due_identity",
39      "name":"Identity Verification Required",
40      "description":"Set entity to RequirementsDue with representative identity fields.",
41      "action":"set_status",
42      "status":"requirements_due",
43      "requirements_due":[
44         "company.representatives.individual.first_name",
45         "company.representatives.individual.last_name",
46         "company.representatives.individual.date_of_birth"
47      ]
48   },
49   {
50      "id":"requirements_due_address",
51      "name":"Address Verification Required",
52      "description":"Set entity to RequirementsDue with address-related fields.",
53      "action":"set_status",
54      "status":"requirements_due",
55      "requirements_due":[
56         "company.principal_address.address_line_1",
57         "company.principal_address.city",
58         "company.principal_address.country",
59         "company.principal_address.zip"
60      ]
61   },
62   {
63      "id":"requirements_due_processing",
64      "name":"Processing Details Required",
65      "description":"Set entity to RequirementsDue with processing detail fields.",
66      "action":"set_status",
67      "status":"requirements_due",
68      "requirements_due":[
69         "company.processing_details.annual_processing_volume",
70         "company.processing_details.average_transaction_value",
71         "company.processing_details.currency"
72      ]
73   },
74   {
75      "id":"pending",
76      "name":"Pending",
77      "description":"Reset entity to Pending status. For ISV sellers, clears requirements due on the data collection work item.",
78      "action":"set_status",
79      "status":"pending",
80      "requirements_due":[
81         
82      ]
83   },
84   {
85      "id":"entity_rejected",
86      "name":"Entity Rejected",
87      "description":"Set entity to Rejected status.",
88      "action":"set_status",
89      "status":"rejected",
90      "requirements_due":[
91         
92      ]
93   },
94   {
95      "id":"entity_restricted",
96      "name":"Entity Restricted",
97      "description":"Set entity to Restricted status.",
98      "action":"set_status",
99      "status":"restricted",
100      "requirements_due":[
101         
102      ]
103   },
104   {
105      "id":"entity_inactive",
106      "name":"Entity Deactivated",
107      "description":"Set entity to Inactive status.",
108      "action":"set_status",
109      "status":"inactive",
110      "requirements_due":[
111         
112      ]
113   },
114   {
115      "id":"enable_payments_and_payouts",
116      "name":"Enable Payments and Payouts",
117      "description":"Enable payments and payouts on an Active entity. Checks that the parent entity has these set as available.",
118      "action":"enable_payments_and_payouts",
119      "status":"",
120      "requirements_due":[
121         
122      ]
123   },
124   {
125      "id":"disable_payments_and_payouts",
126      "name":"Disable Payments and Payouts",
127      "description":"Disable payments and payouts on an Active entity.",
128      "action":"disable_payments_and_payouts",
129      "status":"",
130      "requirements_due":[
131         
132      ]
133   },
134   {
135      "id":"make_payments_and_payouts_available",
136      "name":"Make Payments and Payouts Available",
137      "description":"Set payments and payouts as available on a parent entity profile. Run this on a parent before enabling on sub-entities.",
138      "action":"make_payments_and_payouts_available",
139      "status":"",
140      "requirements_due":[
141         
142      ]
143   }
144]

Simulate onboarding scenarios
Beta

Note

Simulate an onboarding scenario

Information

Information

Response examples

Set a sub-entity to a specific status

Information

Request example

Response examples

Flag pending requirements for a sub-entity

Information

Request example

Response examples

List all available requirements

Information

Response example

List all scenarios

Information

Response example