Process sub-entity bank payouts

Last updated: October 22, 2025

If you're on the Full account type, you can send funds on demand or on a schedule to a sub-entity's bank account.

When you instruct a payout, the funds move from your platform currency account to the sub-entity's external bank account.

Ensure that your sub-entity has passed the required onboarding checks.
Ensure the recipient bank account country is supported by Checkout.com.
Optionally, subscribe to webhooks to receive notifications.

Follow these steps:

Add the recipient bank account details for Checkout.com to verify.
Check the bank account field formatting for the recipient account's country and currency.
Create a payment instrument.
You can then instruct an on-demand payout or schedule payouts.

Before you can send bank payouts, you must add recipient bank details using the Dashboard or API for Checkout.com to verify. If the sub-entity holds funds in multiple currencies, add a bank account for each currency.

Sign in to the Dashboard.
Go to Payments > Processing > Sub-entities.
Select the relevant sub-entity from the list.
Go to Manage account > Payout methods.
Select Add a payout method.
The Add bank account page opens.
Enter the bank account details and upload a bank statement.
Select Confirm and add.
The bank account is added, with Pending status.

When we've verified the bank account details, the status changes to Verified.

Call the Upload a file endpoint to upload a bank statement for Checkout.com to verify the bank details. For instructions, see Upload a file.

You can create a payment instrument for each bank account. The account details are saved securely in the Checkout.com Vault. You receive a unique instrument ID to use in payout requests, instead of entering the bank details every time.

To check which fields are required for the country and currency of the recipient bank account, see Payout formatting or call the Get bank account field formatting endpoint.

Call the Add a payment instrument endpoint, and provide the sub-entity ID as the {id} path parameter.

In the request body, provide the following:

label – Your reference for the payment instrument
type – Set to bank_account.
currency – The account's currency, as an ISO 4217 currency code
country– The account's country, as an ISO 3166 alpha-2 country code
instrument_details.account_number – The alphanumeric value that identifies the account
instrument_details.bank_code – The code that identifies the bank
document.type– Set to bank_statement.
document.file_id– The file ID of the document uploaded when adding bank account details

If you're using a SEPA account, see the API reference for more information.

post

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


1{
2  "label": "Bob's Bank Account",
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}

When you create a payment instrument, it automatically goes through a due diligence verification process. It must successfully pass the verification process before you can proceed to the next step.

When the result is available, you receive one of the following webhooks:

The first payment instrument added for a specific currency is automatically associated to the payouts schedule for that currency. You need to associate any subsequent payment instruments to use as the destination when a payout is made. For more information, see Scheduled payouts.

With on-demand payouts, sub-entity funds are paid out immediately, based on the payout instruction you make.

You can instruct a payout at any point in time, but if you do so on a weekend or public holiday, the payment instruction may be carried out the following working day.

Sign in to the Dashboard.
Go to Payments > Processing > Sub-entities.
Select the relevant sub-entity from the list.
Go to Recent activity > Send payout.
Enter the required details.

You need the instrument_id value for the associated payment instrument to instruct an on-demand payout. To retrieve this value, call the Get payment instrument details endpoint, and provide the:

Sub-entity ID as the {entityId} path parameter
Payment instrument ID as the {id} path parameter

get

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


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}

Then, call the Request a payment or payout endpoint.

In the request body, provide the following:

source.type
source.id
destination.type– Set to id.
destination.id– Set to the instrument_id value from the Get payment instrument details response.
amount
currency
billing_descriptor.reference
processing_channel_id

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "entity",
4    "id": "ent_y3oqhf46pyzuxjbcn2giaqnb44"
5  },
6  "destination": {
7    "type": "id",
8    "id": "src_pdasnoaxrtoevpyh3opgaxcrti"
9  },
10  "amount": 1000,
11  "currency": "GBP",
12  "reference": "PO-215-5721",
13  "billing_descriptor": {
14    "reference": "Payout_descriptor"
15  },
16  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y"
17}

If your payout request was sent successfully, you receive a 202 response, with the status Pending.

If your request was unsuccessful, you receive a 422 or 429 response containing an error code. For more information, see Bank payout response examples.

You receive one of the following webhooks notifying you of the payout status:

You can schedule payouts for any day of the week. However, if scheduled on a weekend or public holiday, the instruction may be carried out on the following business day.

You can also configure different payout schedules for each currency the sub-entity holds funds in.

Sign in to the Dashboard.
Go to Payments > Processing > Sub-entities.
Select the relevant sub-entity from the list.
Go to Manage account > Payout schedule.
Enter the required details and select Save changes.

You must first associate a payment instrument to the payout schedule before scheduling payouts using the API. To do this, call the Update a sub-entity's payout schedule endpoint, and provide the sub-entity ID as the {id} path parameter.

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}

You receive one of the following webhooks notifying you of the payout status:

Process sub-entity bank payouts

Before you begin

How it works

Add bank account details

Add bank account details in the Dashboard

Add bank account details using the API

Create a payment instrument

Get bank account field formatting

Request example

Instruct an on-demand payout

Instruct an on-demand payout in the Dashboard

Response example

Request example

Schedule a payout

Schedule payouts in the Dashboard

Request example