# Process sub-entity bank payouts Checkout.com can send funds on demand or on a schedule to a sub-entity's bank account. When a sub-entity instructs a payout, the funds move from their currency account to their external bank account. --- ## Before you start - Ensure that your sub-entity has passed the required onboarding checks. - Ensure the recipient bank account country is [supported by Checkout.com](https://www.checkout.com/docs/payments/request-payouts/bank-payouts/payout-formatting.md). - Optionally, subscribe to [webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Platforms) to receive notifications. --- ## How it works Follow these steps: 1. Add the recipient bank account details for Checkout.com to verify. 2. Check the bank account field formatting for the recipient account's country and currency. 3. Create a payment instrument. 4. Sub-entity instructs an on-demand or scheduled payout. --- ## Add bank account details Call the [Upload a file](https://api-reference.checkout.com/tag/Disputes/#operation/uploadFile) endpoint to upload a bank statement for Checkout.com to verify the bank details. --- ## Get bank account field formatting To check the required bank account fields and format for the country and currency your sub-entity wants to pay out to, see [Bank account field formatting](https://www.checkout.com/docs/payments/request-payouts/bank-payouts/bank-account-field-formatting.md). --- ## Create a payment instrument Your sub-entity must create a payment instrument for each bank account and holding currency they want to use for payouts. The account details are saved securely in the Checkout.com [Vault](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/accept-payments-with-stored-card-credentials.md). Your sub-entity receives a unique instrument ID to use in payout requests, instead of entering the bank details every time. For more information, see [Add a payment instrument](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/add-payment-instrument.md). --- ## Instruct an on-demand payout With on-demand payouts, sub-entity funds are paid out immediately, based on the payout instruction your sub-entity makes. Your sub-entity can instruct a payout at any point in time, but if your sub-entity does so on a weekend or public holiday, the payment instruction may be carried out the following working day. Your sub-entity needs 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](https://api-reference.checkout.com/tag/Payment-instruments/#operation/getPlatformsPaymentInstrument) endpoint, and provide the: - Sub-entity ID as the `{entityId}` path parameter - Payment instrument 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/{entityId}/payment-instruments/{id}` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/accounts/entities/{entityId}/payment-instruments/{id}` ### Response example ```json { "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga", "label": "Bob's Bank Account", "type": "bank_account", "currency": "GBP", "country": "GB", "document": { "type": "bank_statement", "file_id": "file_wxglze3wwywujg4nna5fb7ldli" }, "status": "verified", "default": true, "instrument_id": "src_pdasnoaxrtoevpyh3opgaxcrti" } ``` Then, call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) 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` > **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** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` #### Request example ```json { "source": { "type": "entity", "id": "ent_y3oqhf46pyzuxjbcn2giaqnb44" }, "destination": { "type": "id", "id": "src_pdasnoaxrtoevpyh3opgaxcrti" }, "amount": 1000, "currency": "GBP", "reference": "PO-215-5721", "billing_descriptor": { "reference": "Payout_descriptor" }, "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y" } ``` If your sub-entity's payout request was sent successfully, you receive a 202 response, with the status `Pending`. If your sub-entity's request was unsuccessful, you receive a 422 or 429 response containing an error code. For more information, see [Bank payout response examples](https://www.checkout.com/docs/payouts/bank-payouts.md#Response_examples). You receive one of the following webhooks notifying you of the payout status: - [Payout paid](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payout_paid.md) - [Payout declined](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payout_declined.md) --- ## Schedule a payout Your sub-entity can schedule payouts for any day of the week. However, payouts scheduled on a weekend or public holiday, the instruction may be carried out on the following business day. You must first associate a payment instrument to the payout schedule before your sub-entity schedules payouts using the API. To do this, 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. > **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 { "ISO": { "enabled": true, "threshold": 100, "payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4", "recurrence": { "frequency": "weekly", "by_day": [ "monday" ] } } } ``` You receive one of the following webhooks notifying you of the payout status: - [Payout paid](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payout_paid.md) - [Payout declined](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payout_declined.md)