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 name | Description |
---|---|
| A short description of what the instrument is for. |
| This refers to the type of instrument. Set this to |
| 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. |
| The two-letter ISO country code of where the account is based. See country codes. |
| A legal document used to verify the bank account. |
| The type of document. |
| 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 |
---|---|
| The account holder's account number. |
| 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.