# Sending a payout

A payout moves money from your account to a saved beneficiary. Its amount plus fee is set aside the moment you create it.

```mermaid
sequenceDiagram
  autonumber
  participant S as Your server
  participant API as Partner API
  participant B as Beneficiary's bank
  S->>API: POST /beneficiaries (once)
  API-->>S: 201 — id: ben_…
  S->>API: GET /balances
  API-->>S: collateral / available
  S->>API: POST /payouts
  alt enough funds
    API-->>S: 201 — created, amount + fee set aside
    API->>B: Send
    B-->>API: Paid → succeeded
  else not enough
    API-->>S: 409 insufficient_collateral
  end
```

## 1. Save the beneficiary

```http
POST /v1/beneficiaries HTTP/1.1
Authorization: Bearer <your API key>
Idempotency-Key: supplier-88-bank
Content-Type: application/json

{
  "type": "bank_account",
  "account_ref": "157203004488",
  "currency": "MYR",
  "details": { "bank_code": "MBBEMYKL", "account_holder": "Acme Payments Sdn Bhd" }
}
```

- Save the returned `id` (`ben_…`). Reuse it for every payout.
- Must be active to receive payouts.

## 2. Check funds

- `GET /balances`, per currency.
- Funded from `collateral`. Some accounts use `available` instead.
- Needed: `amount + fee_amount`. Fee is added on top.

## 3. Create

```http
POST /v1/payouts HTTP/1.1
Authorization: Bearer <your API key>
Idempotency-Key: payout-4821
Content-Type: application/json

{
  "beneficiary_id": "ben_01H8ABCDEFGHJKMNPQRSTVWXYZ",
  "amount": "100.00",
  "currency": "MYR",
  "payment_method": "online_banking",
  "merchant_reference": "payout-4821"
}
```

- `201` → `created`, funds set aside.
- Then `processing` → result. See [Payment lifecycle](/guides/payment-lifecycle).

## Where the money goes

```mermaid
flowchart LR
  bal["Your balance"]
  res["Set aside:<br/>amount + fee"]
  out["Beneficiary"]
  bal -- "POST /payouts" --> res
  res -- "succeeded" --> out
  res -- "failed / expired / cancelled:<br/>all back" --> bal
  res -- "partial:<br/>unsent part back" --> bal
```

| Result | Money |
|---|---|
| `succeeded` | Reached the beneficiary |
| `failed` / `expired` / `cancelled` | All back to you, fee included |
| `partial` | Part sent, fee on that part, rest back |

## Cancel

```http
POST /v1/payouts/pay_01H8ABCDEFGHJKMNPQRSTVWXYZ/cancel HTTP/1.1
Idempotency-Key: payout-4821-cancel
```

- Only while `created` → `cancelled`, funds back.
- Already sending → `409` `payout_not_cancellable`.

## Errors

| Code | Meaning | Do |
|---|---|---|
| `409` `insufficient_collateral` | Collateral < `required` | Top up, retry with **new** key |
| `409` `insufficient_balance` | Available < `required` | Wait for funds, **new** key |
| `404` `beneficiary_not_found` | No active beneficiary with that id | Check id |
| `422` `unsupported_payment` | Method/currency/country not enabled | Ask us to enable |
| `409` `idempotency_conflict` | Key reused, different body | New key |

- Refused → nothing set aside.

---

Part of the Partner API guides: https://docs.beever.xyz/guides/. Full reference: https://docs.beever.xyz