> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay on behalf of your customers

> Let a sub-client pay beneficiaries on behalf of the businesses it serves, from enabling it to sending the payout.

A sub-client can pay a beneficiary on behalf of one of its own customers. The payout leaves from the sub-client's account, and it names the business it is paid for: the **ultimate payor**. Kira screens that business before any money moves for it.

## What it takes

Three things have to be true before a payout on behalf of someone else goes out:

1. The sub-client holds the `pobo` capability.
2. The business it pays for is registered as an ultimate payor and has cleared screening.
3. The payout is paid from the virtual account's USD balance or funded with crypto, pays a SWIFT recipient, is priced with a quotation made for it, and names that payor.

Each one has its own step below. None of them is reported by a webhook, so read the status the step points to.

**1. Request the capability**

[Request a capability](https://docs.kirafin.ai/api-reference/capabilities/request-a-capability.md) with `capability: "pobo"` for a verified business sub-client. The answer carries a `verification_link`.

Send the sub-client to that link. It answers questions about who it pays for and how it screens them, and attaches its policy documents. Compliance then reviews the answers.

[How a request is decided](https://docs.kirafin.ai/reference/capabilities/the-capability-request-object.md#how-a-request-is-decided) covers every outcome. Move on once `status` is `approved`.

**2. Register the ultimate payor**

[Create an ultimate payor](https://docs.kirafin.ai/api-reference/ultimate-payors/create-an-ultimate-payor.md) with the business's legal name, city and country, and the sub-client's `user_id` as `sub_client_id`. Register each business the sub-client pays for once.

Kira screens the payor after the call returns. [How a payor clears](https://docs.kirafin.ai/reference/ultimate-payors/the-ultimate-payor-object.md#how-a-payor-clears) says how to follow it. Move on once `status` is `verified`.

**3. Add the beneficiary**

[Create a recipient](https://docs.kirafin.ai/api-reference/recipients/create-a-recipient.md) for the sub-client with `account.account_type: "SWIFT"`. A payout on behalf of others pays only a SWIFT recipient.

**4. Price the payout**

[Create a quotation](https://docs.kirafin.ai/api-reference/quotations/create-a-quotation.md) for the sub-client's virtual account at version `2026-06-01`, and keep its `quote_id`. If your account is pinned to an earlier version, send `X-Api-Version: 2026-06-01` on this call.

Send it with:

* `pobo: true`,
* `rail: "WIRE_SWIFT"`,
* `target.currency: "USD"`,
* how the payout is funded: `from_held_balance: true` to pay from the USD balance the virtual account holds, or `payment_instructions`, the token and chain you will deposit.

The quote costs more than a plain payout's. It adds a `pobo` line, a percentage of the amount, and its rail fee is `wire_international_swift_pobo_outbound` in place of the SWIFT fee.

**5. Send the payout**

[Execute a payout](https://docs.kirafin.ai/api-reference/payouts/execute-a-payout.md) from the sub-client's virtual account, funded the way the quotation was: from its USD balance, or with crypto. Send it with:

* `pobo: true`,
* `ultimate_payor_id`, the payor's `id`,
* `quote_id`, from the quotation,
* `recipient_id`, the SWIFT recipient.

The payout comes back with `pobo: true`, and so does every later read of it. A payout from the USD balance needs the balance to cover the amount and its fees, as any payout from the balance does.

## What Kira sets up

A payout on behalf of others also needs two things only Kira can set up for the account: a sender account for the sub-client, and the route these payments travel on. It reaches only the recipients that route can pay. Ask your Kira contact to set both up, and which recipients can be paid this way, before you send the first one.

## What goes wrong

The payout is refused before any money moves. Read `code` on the error.

| Status | `code` | What to do |
| - | - | - |
| `422` | `capability_not_granted` | The sub-client does not hold `pobo`. Go back to the first step. |
| `422` | `ultimate_payor_not_found` | The payor is not registered for this account's sub-client. Use one registered for it. |
| `422` | `ultimate_payor_not_cleared` | The payor's `status` is not `verified`. Wait for the screening, or use another payor. |
| `422` | `pobo_requires_swift` | The recipient is not a SWIFT recipient. Pay one that is. |
| `422` | `POBO_QUOTE_MISMATCH` | The quote was not made with `pobo: true`. Create a new quotation with it. |
| `422` | `pobo_sender_account_required`, `pobo_route_unavailable` | Kira has not finished setting the account up. Contact your Kira contact. |
| `503` | `pobo_payout_unavailable` | The payout could not be processed right now and ended `failed`; nothing was debited. Create a new quotation and send the payout again. |
| `400` | `ultimate_payor_required`, `pobo_recipient_required` | A field the payout needs is missing. Add it and send the payout again. |
| `400` | `pobo_quote_required` | `quote_id` is missing, or is not a quotation you made with [Create a quotation](https://docs.kirafin.ai/api-reference/quotations/create-a-quotation.md). |
| `400` | `ultimate_payor_requires_pobo` | `ultimate_payor_id` was sent without `pobo: true`. |
| `400` | `pobo_unsupported_mode` | The payout pays a wallet. A payout on behalf of others pays a SWIFT recipient. |

[Execute a payout](https://docs.kirafin.ai/api-reference/payouts/execute-a-payout.md) lists every error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.