Manage sub-entity bank accounts

Last updated: August 21, 2024

With a Full account, you have complete access to Checkout.com's payouts capabilities. For example, you can pay out to a sub-entity bank account. For us to support you with this, you need to securely store the card details information, using a payment instrument.

To create a card payment instrument:

You must have passed eligibility checks
The issuer country must be a country supported by Checkout.com’s Integrated Platforms solution

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. If the sub-entity holds funds in multiple currencies, you must provide corresponding bank details for each currency. 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.

When a sub-entity is created, a Checkout.com currency account is automatically associated with that sub-entity. In case multiple currencies are held by the sub-entity, separate accounts will be created for each currency. When you request a payment on behalf of your sub-entity, those funds are routed to the corresponding currency account based on the payment routing rules.

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.

There are different requirements for the request, depending on the currency of the bank account. Currently, you can only send money from the UK, European Economic Area (EEA), or US. However, you can perform a payout to any UK, EEA, or US bank account.

The following table outlines the minimum required fields when creating a payment instrument. To get a detailed view of all required and optional fields, see our API reference.

You can create a payment instrument for each of the currencies your sub-entity holds funds in.

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.

Field name	Description
`iban`	Internationally agreed standard for identifying bank account.
`swift_bic`	8- or 11-character code that identified the bank or bank branch.

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.

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}/payment-instruments


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}

If your request is successful, the payment instrument will be created and a payment instrument_id returned.

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


1{
2  "request_id": "71ccac67-5018-4917-9446-f2f6f2b8270e",
3  "error_type": "request_invalid",
4  "error_codes": ["bank_code_invalid"]
5}

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.


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": "cakeshop123456789101112",
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}


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

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}

You can associate an existing payment instrument with a payout schedule. This will make it the destination instrument when a scheduled payout is made.

The first payment instrument added for a specific currency will be automatically associated to the payouts schedule for that currency. Any subsequent payment instruments added will need to be associated explicitly, in order to be used as a destination when a payout is made.

To update the payment instrument for a schedule, use the following end point:

put

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


1{
2  "ISO":{
3    "enabled":true,
4    "threshold":100,
5    "payment_instrument_id":"ppi_w4jelhppmfiufdnatam37wrfc4",
6    "recurrence":{
7      "frequency":"weekly",
8      "by_day":[
9        "monday"
10      ]
11    }
12  }
13}


1{
2  "_links":{
3    "self":{
4      "href":"https://api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
5    }
6  }
7}

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

Process sub-entity payments

Process payments on behalf of your sub-entities.

Manage sub-entity bank accounts

Sub-entity bank details

Checkout.com currency accounts and payment instruments

Requirements for creating a payment instrument

Verify bank account details

Create a payment instrument

Request example

Response examples

Bank account verification notification example

Update a payment instrument

Request example

Response example

Next steps

Process sub-entity payments