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

# Payouts

> Push funds from your pre-funded balance directly to beneficiaries

## What are Payouts?

Payouts are outbound disbursements that let you send funds from your pre-funded KillB balance to any beneficiary — bank accounts, crypto wallets, or local payment aliases. They are the simplest way to distribute money at scale: no quotation step, no payment URL, no waiting for end-user action. You hold the balance; KillB routes it to the destination.

<Info>
  Payouts are a B2B feature designed for businesses that need to disburse funds to many recipients (payroll, supplier payments, marketplace settlements, crypto distributions, etc.).
</Info>

## Payouts vs. Ramps

Both payouts and ramps move money, but they serve different purposes:

|                       | Payouts                                   | Off-Ramps                    |
| --------------------- | ----------------------------------------- | ---------------------------- |
| **Direction**         | Pre-fund → Beneficiary                    | Crypto wallet → Fiat account |
| **Who initiates**     | Your backend                              | Your end-user                |
| **Quotation needed?** | No                                        | Yes                          |
| **Payment URL?**      | No                                        | Yes                          |
| **Use case**          | Batch disbursements, payroll, settlements | User cash-outs               |
| **Balance source**    | Pre-fund account                          | User's crypto wallet         |

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant You as Your Backend
    participant KillB
    participant Bank as Bank / Wallet

    You->>KillB: POST /api/v2/payouts
    Note over KillB: Debit pre-fund balance
    KillB-->>You: { id, status: "CREATED" }
    KillB->>Bank: Route payment through pipeline
    Bank-->>KillB: Confirmation
    KillB-->>You: Webhook: payout.completed
```

## Prerequisites

Every payout requires:

1. **An active pre-funded account** — holds the balance to be disbursed
2. **Sufficient balance** — equal to or greater than the payout amount
3. **Valid beneficiary details** — matching the required fields for the chosen payment rail

<Card title="Set Up Pre-Funded Accounts" icon="vault" href="/guides/pre-fund/pre-fund-accounts">
  Learn how to create and fund your pre-fund accounts
</Card>

## Payout Lifecycle

```mermaid theme={null}
graph LR
    CREATED --> CashIn[Cash In]
    CashIn --> KYTOut[KYT Out]
    KYTOut --> CashOut[Cash Out]
    CashOut --> COMPLETED

    KYTOut -.-> REVIEW_NEEDED
    REVIEW_NEEDED -.-> REJECTED

    KYTOut -.-> FAILED
    KYTOut -.-> ERROR
    CashOut -.-> FAILED
    CashOut -.-> ERROR
    FAILED --> REFUNDED
    ERROR --> REFUNDED
    REJECTED --> REFUNDED

    CashIn -.->|"terminal"| FAILED
    CashIn -.->|"terminal"| ERROR

    style COMPLETED fill:#22c55e,color:#fff
    style REJECTED fill:#f97316,color:#fff
    style FAILED fill:#ef4444,color:#fff
    style ERROR fill:#ef4444,color:#fff
    style REFUNDED fill:#6366f1,color:#fff
    style REVIEW_NEEDED fill:#eab308,color:#000
```

<Warning>
  `FAILED` and `ERROR` during the **Cash In** phase are terminal — no funds were collected, so no refund is issued. For all later phases (KYT Out, Cash Out), these statuses trigger the refund flow. `REJECTED` always triggers the refund flow since it only occurs after funds have been collected.
</Warning>

### Statuses

| Status                | Phase       | Meaning                                                                                              |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `CREATED`             | Initial     | Payout received and persisted, awaiting queue entry                                                  |
| `CASH_IN_PENDING`     | Cash In     | Incoming fund collection queued                                                                      |
| `CASH_IN_PROCESSING`  | Cash In     | Collecting funds from pre-fund balance                                                               |
| `CASH_IN_COMPLETED`   | Cash In     | Funds collected successfully                                                                         |
| `KYT_OUT_PENDING`     | KYT Out     | Outgoing transaction queued for compliance check                                                     |
| `KYT_OUT_PROCESSING`  | KYT Out     | Compliance review in progress (outgoing)                                                             |
| `KYT_OUT_COMPLETED`   | KYT Out     | Outgoing compliance check passed                                                                     |
| `CASH_OUT_PENDING`    | Cash Out    | Disbursement to beneficiary queued                                                                   |
| `CASH_OUT_PROCESSING` | Cash Out    | Funds submitted to payment provider                                                                  |
| `CASH_OUT_COMPLETED`  | Cash Out    | Payment provider confirmed delivery                                                                  |
| `COMPLETED`           | Terminal    | Payout fully settled                                                                                 |
| `REVIEW_NEEDED`       | Review      | Transaction flagged for manual compliance review                                                     |
| `FAILED`              | Error State | Operation failed. Terminal if during Cash In; triggers refund flow if during a later phase.          |
| `REJECTED`            | Error State | Payout blocked by compliance review. Always triggers refund flow since it only occurs after Cash In. |
| `ERROR`               | Error State | Internal system error. Terminal if during Cash In; triggers refund flow if during a later phase.     |
| `REFUND_PENDING`      | Refund      | Refund to pre-fund balance queued                                                                    |
| `REFUND_PROCESSING`   | Refund      | Refund in progress                                                                                   |
| `REFUNDED`            | Terminal    | Funds returned to pre-fund balance                                                                   |

## Supported Beneficiary Types

| Type   | Region   | Description                                  |
| ------ | -------- | -------------------------------------------- |
| `BANK` | Colombia | Bank account transfer via Bank Transfer      |
| `BREB` | Colombia | Registered alias (phone, email, national ID) |

## Idempotency

To prevent duplicate disbursements, pass a unique `Idempotency-Key` header on every payout creation request. If the same key is received twice, KillB returns the original payout instead of creating a new one.

```bash theme={null}
Idempotency-Key: <your-unique-payout-reference>
```

## FAQs

<AccordionGroup>
  <Accordion title="What happens to my balance if a payout fails?" icon="circle-question">
    It depends on which phase the failure occurs in:

    * **During Cash In** — No funds were collected, so nothing is deducted from your pre-fund balance.
    * **After Cash In** (KYT Out, Cash Out) — Funds were already collected. The payout transitions to the refund flow (`REFUND_PENDING` → `REFUND_PROCESSING` → `REFUNDED`), returning them to your pre-fund balance.
  </Accordion>

  <Accordion title="What's the difference between ERROR, FAILED, and REJECTED?" icon="circle-question">
    Each status reflects a different failure origin:

    * **`ERROR`** — An internal system error on KillB's side. No funds were disbursed.
    * **`FAILED`** — The disbursement was declined by the beneficiary's bank due to invalid or incorrect account details provided by the sender.
    * **`REJECTED`** — The payout was blocked by a compliance review on KillB's side. Funds are returned to your pre-fund balance via the refund flow.
  </Accordion>

  <Accordion title="What is REVIEW_NEEDED?" icon="circle-question">
    A payout enters `REVIEW_NEEDED` when the KYT Out compliance check flags the transaction for manual review. No action is required on your side — the payout will automatically resume once the review is complete, or transition to `REJECTED` if blocked.
  </Accordion>

  <Accordion title="When does a REFUNDED status occur?" icon="circle-question">
    A payout reaches `REFUNDED` when `FAILED` or `ERROR` occurs after the Cash In phase (KYT Out or Cash Out), or when the payout is `REJECTED` by compliance. Because funds were already collected, the payout automatically moves through `REFUND_PENDING` → `REFUND_PROCESSING` → `REFUNDED`.

    If `FAILED` or `ERROR` occurs during Cash In, no funds were collected and no refund is issued.
  </Accordion>

  <Accordion title="How long does a payout take?" icon="circle-question">
    Bank Transfer and BREB transfers typically settle within minutes to a few business hours depending on the bank and cut-off times.
  </Accordion>

  <Accordion title="How does idempotency work?" icon="circle-question">
    Pass a unique `Idempotency-Key` header on payout creation requests. If the same key is received twice (e.g., on a retry), KillB returns the original payout instead of creating a duplicate disbursement.
  </Accordion>
</AccordionGroup>

## Best Practices

* **Check balance first** — always call `GET /api/v2/customers/balances` before creating a payout to avoid failures due to insufficient funds
* **Use `Idempotency-Key`** — always pass a unique key per disbursement to safely retry without duplicates
* **Subscribe to webhooks** — configure `PAYOUT` event webhooks for real-time status updates instead of polling
* **Monitor REJECTED payouts** — log full beneficiary data on rejection so you can identify and fix invalid account details
* **Reconcile daily** — pull all payouts from the previous day and compare against your internal ledger

## Related Guides

<CardGroup cols={2}>
  <Card title="Create a Payout" icon="paper-plane" href="/guides/payouts/create-payout">
    Step-by-step implementation guide
  </Card>

  <Card title="Status Tracking" icon="chart-line" href="/guides/payouts/payout-status">
    Monitor payouts with webhooks and polling
  </Card>

  <Card title="Pre-Funded Accounts" icon="vault" href="/guides/pre-fund/pre-fund-accounts">
    Fund your pre-fund accounts
  </Card>

  <Card title="Webhooks" icon="bell" href="/concepts/webhooks">
    Real-time event notifications
  </Card>
</CardGroup>