Skip to content

Manage sub-entity bank accounts

Beta

Last updated: November 2, 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

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. Currently, you can only send money from the UK or European Economic Area (EEA), but you can make a payout to any UK or European bank account.

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.

You can also choose to set the payment instrument as default, so that the associated bank account will be used for your sub-entity’s scheduled payouts.

post

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

Request example

1
{
2
  "label":"Daniel's Donuts Barclays",
3
  "type":"bank_account",
4
  "currency":"GBP",
5
  "country":"GB",
6
  "default": true,
7
  "instrument_details": {
8
    "account_number": "12345678",
9
    "bank_code": "050389"
10
  },
11
  "document": {
12
    "type": "bank_statement",
13
    "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
14
  }
15
}

Response examples

If your request is successful, the payment instrument will be created and an identifier returned. For example, ppi_h5qk7lfsp3ludfjxba256lduju.

You can use this ID value to retrieve details about the payment instrument.

Once the payment instrument has been created, it will automatically go through a due diligence verification process.

The instrument cannot be used until it has successfully passed the verification process. You can use the Workflows API to be notified of the verification process outcome.

Bank account verification notification example

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

Fetch a payment instrument

You can retrieve a payment instrument's ID using the

get

/accounts/entities/{entityId}/payment-instruments/{id} endpoint.

The response's instrument_id value is a unique reference to your instrument's details, which you can use to identify it when using our other APIs. The payment instrument's details are not returned in the response.

1
{
2
  "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
3
  "label": "Bob's Bank Account",
4
  "type": "bank_account",
5
  "currency": "GBP",
6
  "country": "GB",
7
  "document": {
8
    "type": "bank_statement",
9
    "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
10
  },
11
  "status": "verified",
12
  "default": true,
13
  "instrument_id": "src_pdasnoaxrtoevpyh3opgaxcrti"
14
}

Update a payment instrument

You can set an existing payment instrument as default. This will make it the destination instrument when a scheduled payout is made.

To set a payment instrument as default, use the following endpoint:

patch

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

Request example

1
{
2
    "default": true,
3
    "label": "My bank account"
4
}

Response example

1
{
2
    "id": "ppi_yagk5tfrvmrahddwe7rujgblmm",
3
    "_links": {
4
        "self": {
5
            "href": "/ent_huczafesn3zwodyifddw23xnvm/payment-instruments/ppi_yagk5tfrvmrahddwe7rujgblmm"
6
        }
7
    }
8
}

If your request is successful, you'll receive a 200 HTTP response code.

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

On this page

Save a sub-entity's bank details
Fetch a payment instrument
Update a payment instrument
Next steps