Skip to content

Onboard sub-entities with the Accounts API (lite) Beta

Last updated: 9th August 2022

This process should be followed for those on the lite account type for our Platforms solution. We have another page for full sub-entity onboarding.

On this page, we will walk through the complete onboarding of a sub-entity:

  • Onboard a sub-entity
  • Update a sub-entity
  • Retrieve a sub-entity
  • Handle due diligence notifications
  • Testing

Don't want to use code? You can onboard sub-entities using our friendly user interface in the Dashboard.

Before you begin

Configure your webhooks and subscribe to:

  • sub_entity_created
  • vmss_passed and vmss_failed
  • match_passed and match_failed
  • payments_enabled and payments_disabled
  • status_changed

To get a detailed view of all required and optional fields, see our API reference.


Onboard a sub-entity

    post

    https://api.checkout.com/accounts/entities

    Request examples

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      {
      "reference":"678910",
      "contact_details":{
      "phone":{
      "number":"111222333"
      }
      },
      "profile":{
      "urls":[
      "https://www.thecakeshop.com"
      ],
      "mccs":[
      5814
      ]
      },
      "company":{
      "legal_name":"The Cake Shop Inc.",
      "trading_name":"The Cake Shop",
      "principal_address":{
      "address_line1":"90 Tottenham Court Road",
      "city":"London",
      "zip":"W1T4TJ",
      "country":"GB"
      }
      }
      }

      Response examples

        A successful response includes a unique sub-entity id, which you should store for future requests.

        Additionally, the response has the capabilities object, which shows you whether the sub-entity’s capabilities are enabled or not. Capabilities only get enabled once specific due diligence checks have been run and passed.

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        {
        "id": "ent_aotj3m5ggi2ecpfmxu4su5ctx4",
        "reference": "MnuaOoPZanDbJwT",
        "status": "requirements_due",
        "capabilities": {
        "payments": {
        "enabled": false
        },
        "payouts": {
        "enabled": false
        },
        },
        "requirements_due": [
        {
        "field": "individual.date_of_birth",
        "reason": "required"
        },
        ],
        "_links": {
        "self": {
        "href": "https://api.sandbox.checkout.com/accounts/entities/ent_aotj3m5ggi2ecpfmxu4su5ctx4"
        }
        }
        }

        Capabilities are enabled once due diligence checks have been completed. If you haven't received a webhook notification – either {check}_passed or {check}_failed – it is likely there are outstanding requirements due. Please check our onboarding information page to confirm you have sent all the required information.

        If you have provided all the information, we may be completing a manual review.

        Webhook notification example

        Once your sub-entity has been successfully created, we will send you a sub_entity_created webhook notification, which will look similar to:

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        {
        "id": "evt_jqv4f6zedawetlilolhqun6m4m",
        "type": "sub_entity_created",
        "timestamp": "2020-08-20T16:48:17.142+00:00",
        "version": "1.0.0",
        "data": {
        "sub_entity_id": "ent_gavuonbau65upa75f77rar4yuu",
        "reference": "5uperher01234",
        "legal_name": "Super Hero Masks Inc."
        },
        "_links": {
        "self": {
        "href": "https://api.sandbox.checkout.com/workflows/events/evt_jqv4f6zedawetlilolhqun6m4m"
        }
        }
        }

        Update a sub-entity

        You can update all fields under the contact_details, profile, and company objects.

        When you update a sub-entity, we may conduct further due diligence checks when necessary. During these checks, your payment capabilities will remain unchanged.

          put

          https://api.checkout.com/accounts/entities/{id}

          Request examples

          To get a detailed view of all required and optional fields, see our API reference.

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            32
            33
            34
            35
            36
            37
            38
            39
            40
            41
            42
            43
            {
            "reference":"78910",
            "contact_details":{
            "phone":{
            "number":"111222333"
            }
            },
            "profile":{
            "urls":[
            "https://www.thecakeshop.com"
            ],
            "mccs":[
            5814
            ]
            },
            "company":{
            "business_registration_number":"452349600005",
            "legal_name":"The Cake Shop Inc.",
            "trading_name":"The Cake Shop",
            "principal_address":{
            "address_line1":"90 Tottenham Court Road",
            "city":"London",
            "zip":"W1T4TJ",
            "country":"GB"
            }
            },
            "registered_address":{
            "address_line1":"90 Tottenham Court Road",
            "city":"London",
            "zip":"W1T4TJ",
            "country":"GB"
            },
            "representatives":[
            {
            "first_name":"Chrisi",
            "last_name":"Webster",
            "address":{
            "country":"GB"
            }
            }
            ]
            }

            Response example

              If the request was successful, you will receive 200 - Sub-entity updated successfully .

              1
              2
              3
              4
              5
              6
              7
              8
              9
              10
              11
              12
              13
              14
              15
              16
              17
              18
              19
              20
              21
              {
              "id": "ent_wxglze3wwywujg4nna5fb7ldli",
              "reference": "superhero1234",
              "status": "pending",
              "capabilities": {
              "payments": {
              "enabled": false
              },
              "payouts": {
              "enabled": false
              },
              "requirements_due": [
              ],
              "_links": {
              "self": {
              "href": "https://api.sandbox.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
              }
              }
              }
              }

              Capabilities are enabled once due diligence checks have been completed. If you haven't received a webhook notification – either {check}_passed or {check}_failed – it is likely there are outstanding requirements due. Please check our onboarding information page to confirm you have sent all the required information.

              If you have provided all the information, we may be completing a manual review.


              Retrieve a sub-entity

              If you need to retrieve a sub-entity's details, you can use our Get sub-entity details endpoint. Just include the id of the sub-entity returned during the initial onboarding in your request. For example, https://api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli.

                get

                https://api.checkout.com/accounts/entities/{id}

                Response examples

                The response allows you to retrieve all data that has been provided about the sub-entity, including its capabilities, which informs you whether this sub-entity can process payments or not.

                  1
                  2
                  3
                  4
                  5
                  6
                  7
                  8
                  9
                  10
                  11
                  12
                  13
                  14
                  15
                  16
                  17
                  18
                  19
                  20
                  21
                  22
                  23
                  24
                  25
                  26
                  27
                  28
                  29
                  30
                  31
                  32
                  33
                  34
                  35
                  36
                  37
                  38
                  39
                  40
                  41
                  42
                  43
                  {
                  "id": "ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
                  "reference": "0123456",
                  "status": "active",
                  "capabilities": {
                  "payments": {
                  "enabled": true
                  },
                  "payouts": {
                  "enabled": false
                  }
                  },
                  "profile": {
                  "default_holding_currency": "GBP",
                  "urls": ["https://www.daniels-donuts.com"],
                  "mccs": ["5814"]
                  },
                  "individual": {
                  "first_name": "Daniel",
                  "last_name": "Yubi",
                  "trading_name": "Daniel's Donuts",
                  "legal_name": "Daniel Yubi",
                  "national_tax_id": "1234567",
                  "registered_address": {
                  "address_line1": "90 Tottenham Court Road",
                  "city": "London",
                  "zip": "W1T4TJ",
                  "country": "GB"
                  }
                  },
                  "contact_details": {
                  "phone": {
                  "number": "2345678910"
                  }
                  },
                  "instruments": [],
                  "requirements_due": [],
                  "_links": {
                  "self": {
                  "href": "https://api.sandbox.checkout.com/accounts/entities/ent_vv2jjkuf2gzj5tcw2x7ptua7zy"
                  }
                  }
                  }

                  The legal_name field is auto-generated based on the first_name, middle_name and last_name provided during onboarding.

                  We require profile.default_holding_currency for full account types, so we set a default in case you would like to change to the full account type. This doesn't have any impact on the way that funds will be routed and held for this sub-entity.

                  profile.default_holding_currency is not currently updatable. If you need to change this, please get in touch.

                  Capabilities are enabled once due diligence checks have been completed. If you haven't received a webhook notification – either {check}_passed or {check}_failed – it is likely there are outstanding requirements due. Please check our onboarding information page to confirm you have sent all the required information.

                  If you have provided all the information, we may be completing a manual review.


                  Handle due diligence notifications

                  Once we have conducted our due diligence checks, we will inform you of the outcome via webhook notification. You should expect to receive the following event types:

                  • vmss_passed / vmss_failed
                  • match_passed / match_failed

                  Due diligence will always pass in the Sandbox environment, unless one of our legal_name fail triggers is used for simulation.

                  On occasion, our team will need to manually review a sub-entity. Please see our onboarding page for more information.

                  Due diligence webhook example

                  We've described the different webhook notifications on our webhook event type page.

                    1
                    2
                    3
                    4
                    5
                    6
                    7
                    8
                    9
                    10
                    11
                    12
                    13
                    14
                    15
                    16
                    17
                    {
                    "id": "evt_htielsmgcwgejgqaunl4yb2pou",
                    "type": "vmss_passed",
                    "version": "1.0.0",
                    "created_on": "2020-08-20T15:24:13.8431084Z",
                    "data": {
                    "sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
                    "reference": "123456789101112",
                    "legal_name": "The Cake Shop Inc."
                    },
                    "_links": {
                    "self": {
                    "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
                    }
                    }
                    }

                    If due diligence is passed (VMSS and Match), we will enable the sub-entity’s payments capability. You should expect to receive the payments_enabled event type.

                    We will re-trigger due diligence checks if legal_name, trading_name and profile.urls is later updated. If any subsequent checks fail and you receive the vmss_failed or match_failed notification, this will be followed by a payments_disabled webhook notification.

                    Payments enabled webhook example

                    1
                    2
                    3
                    4
                    5
                    6
                    7
                    8
                    9
                    10
                    11
                    12
                    13
                    14
                    15
                    16
                    {
                    "id": "evt_htielsmgcwgejgqaunl4yb2pou",
                    "type": "payments_enabled",
                    "version": "1.0.0",
                    "created_on": "2020-08-20T15:24:13.8431084Z",
                    "data": {
                    "sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
                    "reference": "123456789101112",
                    "legal_name": "The Cake Shop Inc."
                    },
                    "_links": {
                    "self": {
                    "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
                    }
                    }
                    }

                    Testing

                    You can simulate different scenarios when onboarding sub-entities. Similar to simulating payment scenarios using specific card numbers, you can use certain values in the legal_name field of your onboarding request. This will trigger specific outcomes regarding card scheme screening, as well as the payment capabilities of a sub-entity.

                    Including a company name in the legal_name field will trigger positive VMSS and MATCH checks, and will enable payment capabilities. The simulator only accepts fail triggers:

                    Trigger to be added in legal_nameCard scheme screeningPayment capabilities

                    simulator_match_fail simulator_vmss_fail

                    Both the VMSS and the MATCH checks fail.

                    Remain disabled.

                    simulator_vmss_fail

                    The VMSS check fails, but the MATCH check passes.

                    Remain disabled.

                    simulator_match_fail

                    The VMSS check passes, but the MATCH check fails.

                    Remain disabled.

                    Next steps


                    Accept a payment

                    Process payments on behalf of your sub-entities.


                    Find out more


                    Status types

                    Find out more about status types during the onboarding process.