Skip to content

Sub-entity payouts

Beta

Last updated: November 11, 2022

There are different options available depending on what account type you were onboarded with. If you're unsure which account type you are, please see our account structure page or contact us.

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

Client settlements for lite account type

For those on the lite account type, all funds will be settled to your platform’s designated bank account(s) as per the frequency agreed during your onboarding.

The distribution of funds to your sub-entities and collection of fees for your platform are both done outside of our solution.

You can optionally process daily balance reports and financial actions reports to retrieve the closing available balance of your currency account(s) and perform reconciliation.

Payouts solutions for full account type

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

Before they can receive a payout, you must add a bank account payment instrument to your sub-entity.

On payout, the funds will move from your Platform currency account to the sub-entity's external bank account.

Note

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

Scheduled payouts

With scheduled payouts, sub-entity funds will be paid out as per the schedule agreed during your onboarding – daily, by weekdays, or by days in a month.

You can schedule payouts for any day of the week, but those scheduled for a weekend or bank holiday may result in the payment instruction being carried out on the following working day.

To trigger a scheduled payout, you need to set a default payment instrument.

Retrieve a sub-entity's schedule through the API

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

get

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

Response example

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

Update a sub-entity's schedule through the API

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

put

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

Request example

The frequency of a payout can be set to weekly, daily or monthly. If selecting weekly or monthly, you can specify either days of the week, or days of the month.

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

Response example

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

Receive notifications about scheduled payouts

Get notified about your scheduled payouts by subscribing to the following webhook notifications:

  • payout_paid
  • payout_declined

On-demand payouts

With on-demand payouts, sub-entity funds will be paid out on demand based on the payout instruction made.

You can instruct a payout at any point in time, but for those instructed on a weekend or bank holiday, the payment instruction may be carried out the following working day.

Retrieve a sub-entity's payment instrument ID

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

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

get

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

Response example

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
}

Instruct an on-demand payout

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

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

post

https://api.checkout.com/payments

Request example

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
}

Response example

If your payout request was successfully sent, 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.

Receive notifications about on-demand payouts

Get notified about your on-demand payouts by subscribing to the following webhook notifications:

  • payment_paid
  • payment_declined
  • payment_returned

Find out more

Platforms

Find out all you need to know about our Platforms solution – from onboarding to processing your first payment or payout.

Read our documentation for Platforms

On this page

Client settlements for lite account type
Payouts solutions for full account type
Find out more