Process sub-entity bank payouts

Last updated: November 01, 2023

Checkout.com offers different options to give you flexibility over your payouts processing. The options available to you depend on what account type you were onboarded with.

Information

If you're unsure which account type you are, see our account structure page or contact us.

Choose your account from the following headings to find out what payout options are available to you.

If you're on a lite account, all funds are settled to your platform’s designated bank accounts at the frequency agreed during your onboarding.

The distribution of funds to your sub-entities and the collection of your platform fees are both performed externally, by you.

To retrieve the closing available balance of your currency accounts and perform reconciliation, you can generate a daily Balance Report and Financial Actions by Payout ID Report.

If you're on a full account, you can manage payouts using our API or through the Dashboard. We offer the following solutions for this account type:

Before you can send payouts to a sub-entity, you must create a bank account payment instrument, so we know where to send the funds. If the sub-entity holds funds in multiple currencies, you can add bank accounts for each currency.

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

Note

Your sub-entity will not be eligible to receive payouts until it has passed onboarding checks (CSS, KYB, KYC, and PEP) and bank account verification.

With scheduled payouts, sub-entity funds will be paid out as per the schedule agreed during your onboarding. For example, daily, weekly, or monthly.

You can schedule payouts for any day of the week, but those scheduled for a weekend or public holiday may result in the payment instruction being carried out on the following working day. Additionally, you can configure different payout schedules for each currency the sub-entity holds funds in.

To set up scheduled payouts, you must associate a payment instrument to the payout schedule.

get

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

To get a detailed view of all required and optional fields, see our API reference.


1{
2  "GBP": {
3    "enabled": true,
4    "threshold": 0,
5    "recurrence": {
6      "frequency": "Weekly",
7      "by_day": ["Friday"]
8    }
9  },
10  "_links": {}
11}

put

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

To get a detailed view of all required and optional fields, see our API reference.

Payouts can be scheduled daily, weekly, or monthly. If you schedule weekly payouts, you can specify which day of the week. If you schedule monthly payouts, you can specify which date every month.


1{
2  "EUR": {
3    "enabled": true,
4    "threshold": 100,
5    "recurrence": {
6      "frequency": "daily"
7    }
8  }
9}


1{
2  "EUR": {
3    "enabled": true,
4    "threshold": 100,
5    "recurrence": {
6      "frequency": "weekly",
7      "by_day": ["monday", "wednesday"]
8    }
9  }
10}


1{
2  "EUR": {
3    "enabled": true,
4    "threshold": 100,
5    "recurrence": {
6      "frequency": "monthly",
7      "by_month_day": [1, 15, 28]
8    }
9  }
10}


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

Note

If you've enabled webhook notifications, you'll be notified of the event through a webhook.

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.

Use the following endpoint to retrieve the instrument_id value, which you will need when making an on-demand payout request.

get

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

To get a detailed view of all required and optional fields, see our API reference.


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}

Set the destination.id field to the instrument_id value you received in the GET payment instrument details response.

post

https://api.checkout.com/payments

To get a detailed view of all required and optional fields, see our API reference.


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 will receive a 202 response, with the status Pending. If your request was unsuccessful, you will receive a 422 or 429 response containing an error code. See bank payout response examples.

Note

If you've enabled webhook notifications, you'll be notified of the event through a webhook.

Process sub-entity bank payouts

Information

Client settlements for lite account

Payouts solutions for full account

Before you begin

Note

Scheduled payouts

Response example

Update a sub-entity's schedule through the API

Request example

Response example

Note

On-demand payouts

Retrieve a sub-entity's payment instrument ID

Response example

Instruct an on-demand payout

Request example

Response example

Note