Skip to content

Manage sub-entity bank accounts Beta

Last updated: 9th August 2022

Full account types have payout capabilities. In order to pay out to a sub-entity, we need to securely store their bank account information. This page walks through how.

Save a sub-entity's bank details securely

Before making scheduled payouts to a sub-entity, you need to connect bank details to their account, so we know where to send the funds. These details are saved securely in our vault, and you are given a unique reference to use in payout requests instead of typing out the bank details every time. We call this a payment instrument.

Payment instrument vs Checkout.com currency account

When a sub-entity is created, a Checkout.com currency account is automatically associated with that sub-entity. When you request a payment on behalf of your sub-entity, those funds are routed to that currency account.

Using our payouts solution, those funds are then paid out to the external bank account of the sub-entity by using the secure payment instrument.

Requirements for creating a payment instrument

There are different requirements for the request depending on the currency of the bank account. At the moment, you can just send money from the UK, but you can make a payout to UK bank accounts and European bank accounts.

The table below outlines the minimum required fields when creating a payment instrument. You can see the full explanation of the optional fields in our API reference.

Field nameDescription

label

A short description of what the instrument is for.

type

This refers to the type of instrument. Set this to bank_account.

currency

This is the three-letter ISO currency code of the account's currency. At the moment, this would be GBP or EUR.

See currency codes.

country

The two-letter ISO country code of where the account is based.

See country codes.

document

A legal document used to verify the bank account.

document.type

The type of document.

document.file_id

The ID of the file representing the uploaded document.

Use the following table to review additional required fields, depending on the currency.

Where are you sending the money to?

    Field nameDescription

    account_number

    The account holder's account number.

    bank_code

    The account holder's sort code.

    Verify bank account details

    We need to verify any bank details you provide us. To verify bank details, include a document object with a file_id in your request. You receive a file_id when you upload a bank statement using our Files API.

    Create a payment instrument

    To create a payment instrument, make a call to the following endpoints. To get a detailed view of all required and optional fields, see our API reference.

      post

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

      Request example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      {
      "label":"Daniel's Donuts Barclays",
      "type":"bank_account",
      "account_number":"12345678",
      "bank_code":"050389",
      "currency":"GBP",
      "country":"GB",
      "account_holder":{
      "company_name":"Daniel's Donuts",
      "billing_address":{
      "address_line1":"90 Tottenham Court Road",
      "city":"London",
      "state":"London",
      "zip":"W1T 4TJ",
      "country":"GB"
      }
      },
      "document": {
      "type": "bank_statement",
      "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
      }
      }

      Response examples

        If your request is accepted, we will attempt to create a payment instrument asynchronously (behind the scenes) and inform you of the outcome via webhook notification. The webhook will include the unique reference to the bank details, and looks like src_h5qk7lfsp3ludfjxba256lduju.

        If successful, we will automatically make the association between this payment instrument and its sub-entity. You can see this association and alternatively retrieve the payment instrument ID by using get/accounts/entities/{id}.

        1
        2
        3
        4
        5
        6
        7
        8
        9
        {
        "id": "ent_wxglze3wwywujg4nna5fb7ldli",
        "instruments": [
        {
        "id": "src_33z5qxrwp2bulj4volyqvarhyq",
        "label": "Daniel's Donuts Barclays"
        }
        ]
        }

        Notifications

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          16
          17
          18
          19
          20
          {
          "id": "evt_htielsmgcwgejgqaunl4yb2pou",
          "type": "payment_instrument_created",
          "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.",
          "payment_instrument": {
          "id": "src_h5qk7lfsp3ludfjxba256lduju",
          "label": "The Cake Shop Barclays"
          }
          },
          "_links": {
          "self": {
          "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
          }
          }
          }

          Next steps


          Make a payout

          Full accounts on our solution have payout capability. If you’re unsure, take a look at our account structure page.

          Upload a file

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