Skip to content

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

Last updated: 9th August 2022

This process should be followed for those on the full account type for our Platforms solution. We have another page for lite 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
  • Add supporting documentation
  • Retrieve a sub-entity
  • Handle due diligence notifications

Before you begin

Configure your webhooks and subscribe to:

  • sub_entity_created
  • full_dd_passed and full_dd_failed
  • payouts_enabled and payouts_disabled
  • payments_enabled and payments_disabled
  • status_changed

Onboard a sub-entity

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

    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 will include 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
        25
        26
        27
        28
        {
        "id": "ent_wxglze3wwywujg4nna5fb7ldli",
        "reference": "123456789101112",
        "status": "requirements_due",
        "capabilities": {
        "payments": {
        "enabled": false
        },
        "payouts": {
        "enabled": false
        },
        "requirements_due": [
        {
        "field": "individual.date_of_birth",
        "reason": "required"
        },
        {
        "field": "individual.identification.document",
        "reason": "required"
        },
        ],
        "_links": {
        "self": {
        "href": "https://api.sandbox.checkout.com/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.

        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

        Use this endpoint to update all fields under the contact_details, profile, and company objects. To get a detailed view of all required and optional fields, see our API reference.

          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
            44
            45
            46
            47
            48
            49
            50
            51
            52
            53
            54
            55
            56
            57
            {
            "reference":"678910",
            "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":{
            "address_line1":"123 ABC Close",
            "city":"London",
            "zip":"E1 5DP",
            "country":"GB"
            },
            "date_of_birth":{
            "day":5,
            "month":6,
            "year":1995
            },
            "identification": {
            "document": {
            "type": "Passport",
            "front": "file_jxaps37jnfaupfu6bsei7rj5iu",
            "back": "file_zn6v47bgphjuljjvhlpk7dnpby"
            }
            }
            }
            ],
            }
            }

            Response examples

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

              Add supporting documentation

              Use our Files API to upload:

              • Identification for know your customer (KYC) due diligence checks
              • Documentation to verify a company for know your business (KYB) checks

              The Files API returns an id that represents that file. Use this to add supporting documentation while onboarding a sub-entity, or when you update the sub-entity.

              Identification

              All you need to include is the identification.document object in your request, with the following pieces of information:

              • Type: Read more about what types are accepted.
              • Front: Required for all identification types. This should be the id returned when you uploaded the file
              • Back: Only required if the type is not a passport. This should be the id returned when you uploaded the file
                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
                {
                ...
                "individual":{
                "first_name":"Daniel",
                "last_name":"Yubi",
                "trading_name":"Daniel's Donuts",
                "national_tax_id":"1234567",
                "registered_address":{
                "address_line1":"90 Tottenham Court Road",
                "city":"London",
                "zip":"W1T4TJ",
                "country":"GB"
                },
                "date_of_birth":{
                "day":5,
                "month":6,
                "year":1995
                },
                "identification": {
                "document": {
                "type": "passport",
                "front": "file_jxaps37jnfaupfu6bsei7rj5iu"
                }
                }
                }
                }

                Adding an identification document

                Providing an identity document is the last step before triggering due diligence checks. To prevent multiple due diligence checks, please add all representatives before uploading their identification documents.

                Company verification

                Only needed for sub-entities who have been onboarded as a company.

                All you need to include is the company.document object in your request, with the following pieces of information:

                • File ID: This should be the id returned when you uploaded the file
                • Type: The type of document you are providing. For example, certificate of incorporation
                1
                2
                3
                4
                5
                6
                7
                8
                9
                10
                11
                12
                13
                14
                15
                16
                17
                18
                19
                20
                {
                ...
                "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"
                },
                "document":{
                "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
                "type": "Certificate of incorporation"
                }
                ...
                }
                }

                Retrieve a sub-entity

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

                  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:

                    • full_dd_passed / full_dd_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
                      {
                      "id": "evt_htielsmgcwgejgqaunl4yb2pou",
                      "type": "full_dd_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, we will enable the sub-entity’s payments and payouts capabilities. You should expect to receive the payments_enabled and payout_enabled event types.

                      We will re-trigger due diligence checks if any of the required information is later updated. If any subsequent checks fail and you receive the full_dd_failed notification, this will be followed by payments_disabled and payouts_disabled webhook notifications.

                      Payment and payout webhook examples

                      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
                        {
                        "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"
                        }
                        }
                        }

                        We will re-trigger due diligence checks if any of the required information is later updated. If any subsequent checks fail and you receive the vmss_failed and / or match_failed notification, this will be followed by payments_disabled.

                        Next steps


                        Accept a payment

                        Process payments on behalf of your sub-entities.

                        Find out more


                        Upload a file

                        We'll explain how to upload a file using the Files API.