Platforms / Onboarding / API / Full / Manage bank accounts

Manage sub-entity bank accounts Early access

Last updated: 14th July 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 name	Description
`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 name	Description
`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

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

{
  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "instruments": [
    {
      "id": "src_33z5qxrwp2bulj4volyqvarhyq",
      "label": "Daniel's Donuts Barclays"
    }
  ]
}

Notifications

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

Read our payouts documentation

Upload a file

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

Find out how to upload a file