Onboarding Simulator

​

Endpoints for driving entity state in sandbox environments. These endpoints are sandbox-only and return 404 in production. Use them to simulate status transitions and requirements-due scenarios when testing your integration.

Onboarding Simulator Operations

Set requirements due

​

Sandbox only — not available in Production.

Marks the specified requirement fields as due on an entity. Use this to test how your integration handles the requirements-due state.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the entity.

Body·
required
application/json

The requirement fields to mark as due.

  • fields
    Type: array string[]
    required

    The requirement fields to mark as due.
    Call the List available requirements endpoint for a list of valid values.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized

  • 404

    Entity not found

  • application/json
Request Example for post/simulate/entities/{entityId}/requirements-due
curl 'https://{prefix}.api.sandbox.checkout.com/simulate/entities/ent_w4jelhppmfiufdnatam37wrfc4/requirements-due' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "fields": [
    "individual.identification.document"
  ]
}'

{
  "entity_id": "ent_w4jelhppmfiufdnatam37wrfc4",
  "previous_status": "Active",
  "current_status": "requirements_due",
  "requirements_due": [
    "individual.identification.document"
  ]
}

Requirements due set successfully

Run scenario

​

Sandbox only — not available in Production.

Executes a pre-defined scenario against an entity, triggering the associated state transition or capability change. Use GET /simulate/scenarios to list available scenario IDs.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the entity.

  • scenarioId
    Type: string
    required

    The ID of the scenario to run.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized

  • application/json
  • application/json
Request Example for post/simulate/entities/{entityId}/scenarios/{scenarioId}
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/simulate/entities/ent_w4jelhppmfiufdnatam37wrfc4/scenarios/go_active' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "entity_id": "ent_w4jelhppmfiufdnatam37wrfc4",
  "scenario_id": "go_active",
  "scenario_name": "Go Active",
  "previous_status": "RequirementsDue",
  "current_status": "Active",
  "requirements_due": [
    "individual.identification.document"
  ]
}

Scenario executed successfully

Set entity status

​

Sandbox only — not available in Production.

Forces the entity to the specified status, bypassing normal onboarding flow. Use this to test how your integration handles different entity states.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the entity.

Body·
required
application/json

The status to apply to the entity.

  • status
    Type: string enum
    required

    The status to set on the entity.

    values
    • draft
    • requirements_due
    • pending
    • active
    • restricted
    • rejected
    • inactive
Responses
  • application/json
  • application/json
  • application/json
  • 401

    Unauthorized

  • 404

    Entity not found

  • application/json
Request Example for post/simulate/entities/{entityId}/status
curl 'https://{prefix}.api.sandbox.checkout.com/simulate/entities/ent_w4jelhppmfiufdnatam37wrfc4/status' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "status": "active"
}'

{
  "entity_id": "ent_w4jelhppmfiufdnatam37wrfc4",
  "previous_status": "Pending",
  "current_status": "Active"
}

Status updated successfully

List available requirements

​

Sandbox only — not available in Production.

Returns all requirement fields that can be set as due on an entity. Use the field values when calling the Set requirements due endpoint.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Simulator not available in this environment. These endpoints are not registered in production.

Request Example for get/simulate/requirements-due
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/simulate/requirements-due' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "field": "individual.identification.document",
    "type": "string"
  }
]

Requirements listed successfully

List scenarios

​

Sandbox only — not available in Production.

Returns all pre-defined scenarios available. Use the scenario IDs when calling the run scenario endpoint.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Simulator not available in this environment. These endpoints are not registered in production.

Request Example for get/simulate/scenarios
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/simulate/scenarios' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": "go_active",
    "name": "Go Active",
    "description": "Transitions the entity to active status.",
    "action": "set_status",
    "status": "active",
    "requirements_due": [
      "individual.identification.document"
    ]
  }
]

Scenarios listed successfully