# Manage sub-entity settlements

When Checkout.com captures funds from customers on behalf of your sub-entities, we can transfer the funds to each sub-entity's bank account as a settlement payout.

---

## How it works

1. When Checkout.com captures a payment, the funds enter your sub-entity's [_Pending_](https://www.checkout.com/docs/funds-management/manage-funds/balances.md#Pending_balance) balance. We set a date for when the funds become available. When funds become available, they can be settled or used for other use cases such as [payouts](https://www.checkout.com/docs/platforms/for-saas/process-sub-entity-payouts.md) on your Checkout.com account.
2. Every day at midnight in your sub-entity's settlement time zone, the funds in their _Pending_ balance that have become available are batched and move to their [_Available_](https://www.checkout.com/docs/funds-management/manage-funds/balances.md#Available_balance) balance.
3. When the sub-entity's next settlement is generated, the funds move from their _Available_ to their [_Payable_](https://www.checkout.com/docs/funds-management/manage-funds/balances.md#Payable_balance) balance.
4. The settlement is paid out from their _Payable_ balance to the sub-entity's bank account according to their settlement schedule. Alternatively, your sub-entity can [instruct a payout](https://www.checkout.com/docs/platforms/for-saas/process-sub-entity-payouts/process-sub-entity-bank-payouts.md#Instruct_an_on-demand_payout) on demand.

---

## Settlement time zone

The sub-entity's settlement time zone determines when payments move from _Pending_ to _Available_.
By default, payments are batched for an entire day, from midnight to the following midnight, in the sub-entity’s local time zone.

Payments processed on non-business days are included in the batch on the next business day.

If the sub-entity's settlement time zone is set to UTC, their settlements are generated at 2:00 AM UTC.
For all other time zones, settlements are generated at 5:00 AM local time, based on the regional Checkout.com entity your sub-entity is contracted with.
Settlements are then paid out at the configured settlement schedule.

---

## Settlement schedule

Your sub-entity can schedule to receive settlements at one of the following frequencies in their preferred time zone:

- Daily – Weekdays, excluding non-business days
- Weekly – A weekday of choice, excluding non-business days
- Monthly – First or 15th of each month

If a scheduled settlement is due to be paid out on a non-business day in the selected settlement time zone, the funds are paid out on the following business day instead.

---

## Settlement speed

The settlement speed is the period between time of sale and when the funds in your sub-entity's _Pending_ balance become available.
This may range from a few minutes to a few days.

Settlement speed is usually represented as T+X, where:

- T is the transaction date.
- X is the number of business days after the transaction date that the funds become available.

For example, a payment is processed on Tuesday and the currency’s standard settlement speed is T+2.
The funds become available on Thursday, and are paid out in the next settlement.
If your sub-entity's settlement schedule is:

- Daily – The funds are paid out on Thursday.
- Weekly on Fridays – The funds are paid out on Friday.

When funds are available and ready for settlement, all payments processed on that business day are batched and moved from _Pending_ to your _Available_ balance shortly after midnight.
Payments processed on non-business days are included in the batch on the next business day.

### Currency holidays

A currency holiday is a day when local banks do not convert specific currencies.

Currency holidays and non-business days may delay the standard settlement speed. Currency holidays are set by the settlement currency (US dollar).

---

## Subscribe to webhooks

You can set up webhooks to be notified about settlement events:

1. [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).
2. [Subscribe to settlements webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Settlements).

> **Information**
>
> [Settlement debited](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/settlement_debited.md) webhooks are not sent in Checkout.com for SaaS integrations.

---

## Get sub-entity settlement schedule

Call the [Retrieve a sub-entity's payout schedule](https://api-reference.checkout.com/tag/Payout-schedules/#operation/getSubEntitysPayoutSchedule) endpoint, and provide the sub-entity ID as the `{id}` path parameter.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/accounts/entities/{id}/payout-schedules`

### Response example

```json
{
  "USD": {
    "recurrence": {
      "enabled": true,
      "threshold": 100,
      "payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4",
      "schedule": {
        "frequency": "weekly",
        "by_day": [
          "monday"
        ]
      }
    },
    "_links": {
      "self": {
        "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
      }
    }
  }
}
```

---

## Update sub-entity settlement schedule

Call the [Update a sub-entity's payout schedule](https://api-reference.checkout.com/tag/Payout-schedules/#operation/putSubEntitysPayoutSchedule) endpoint, and provide the sub-entity ID as the `{id}` path parameter.

In the request body, provide at least one of the following fields, and replace `{ISO}` with `USD`:

- `{ISO}.enabled` - Indicates whether the payout schedule is enabled.
- `{ISO}.threshold` – The minimum available balance on the account for a payout. If the available balance is less than the threshold, then the payout is not instructed.
- `{ISO}.payment_instrument_id` - The payment instrument ID used for payouts on this schedule.
- `{ISO}.recurrence.frequency` - The frequency at which funds are paid out to the sub-entity.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

`PUT` `https://{prefix}.api.sandbox.checkout.com/accounts/entities/{id}/payout-schedules`

### Request example

```json
{
  "USD": {
    "enabled": true,
    "threshold": 100,
    "payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4",
    "recurrence": {
      "frequency": "weekly",
      "by_day": [
        "tuesday"
      ]
    }
  }
}
```