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

# Withdrawals

> Move money from your main account to your own bank account or phone.

A withdrawal is a payout to an account you own. The dashboard calls it a withdrawal; the API calls it a settlement (`/settlements`), and the two are the same thing. It's checked by two people: one person requests it, and a different person approves it.

**1. Add a destination**

`POST /v1/merchants/{id}/settlement-destinations` with a bank account or an M-Pesa phone. Cloudpay verifies that it belongs to your business before any money can go there. Until then, settlements to it return `403 destination_unverified`.

**2. Request**

```json theme={null}
POST /v1/merchants/{id}/settlements
{ "destination_id": "…", "amount": 10000000, "idempotency_key": "settle-2026-11-16" }
```

This needs the `settle` scope, approved KYB, and a live key.

**3. Approve**

If the amount is within your auto-approve limits, the settlement is approved straight away (`approved_by: system:auto-approve`). Otherwise someone else with `settle` calls `POST …/settlements/{sid}/approve`. If the person who requested it tries to approve it, they get `403 same_approver`.

**4. Paid**

A settlement to an M-Pesa destination on your payout rail is sent automatically (`payout: rail`). Any other destination is paid by Cloudpay staff (`payout: manual`) and shows `awaiting_payout` until then. Follow the [settlement statuses](https://docs.cloudpay.africa/concepts/lifecycle.md#settlements).

Until a settlement is approved, the requester can cancel it with `POST …/cancel`, and anyone with `settle` can reject it with `POST …/reject`. Trying either after approval returns `409 settlement_state`.


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