Skip to main content
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

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.
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.