Skip to main content
Pay Jane Doe $500.00 and follow the payout until the money has left your Cleff Account. For developers wiring payouts into their product. Each step below is one request, and each response that carries money is read back in plain English.
Agents: fetch this page as plain markdown at https://docs.usecleff.com/guides/send-a-payout.md.
You need a sandbox API key exported as CLEFF_API_KEY, and Jane onboarded with her status reading ready and her ID exported as BEN_ID. Onboard a Beneficiary gets her there. What each state below means is on Payouts.
1

Check you can cover the payout

In production your balance isn’t checked when you create or approve a payout, only when it is sent, so check it first:
In this example your Cleff Account holds $12,500.00 USD; available_balance_minor is 1250000 because amounts are in minor units. That covers Jane’s $500.00.
2

Create the payout

Mint an idempotency key and keep it for as long as you might resend the request:
Name who to pay and how much. Leave out destination_id, so the payout goes to Jane’s declared destination, or to her only one if she has declared none:
The response is trimmed to the fields that matter here. Jane Doe is owed $500.00 USD, to be paid to the bank account destination_id names; amount_minor is 50000 because amounts are in minor units. Nothing has moved: the payout is pending_approval, and its destination is now fixed even if Jane chooses a different one later.Resending this request with the same key within 24 hours returns this payout with HTTP 200 instead of creating a second one. See Idempotency.
3

Approve it

Nothing is sent without a Decision. Approve the payout with a decision_id you mint, a ULID, which makes the approval safe to retry:
The response is trimmed. It is the Decision you recorded; the payout itself is now approved and queued to be sent. To refuse the payout instead, reject it with at least one reason; rejection is terminal.
4

Watch it disburse

Read the payout until state moves from approved to disbursed:
$500.00 USD has left your Cleff Account for Jane’s bank account, and rail_ref is the payment’s reference on the rail, or null until the rail assigns one. In sandbox the payout stops here. In production it is provisional until it becomes settled, and the receiving bank can still return it; Payouts explains the rest of the way.
5

Hear about it instead of polling

In place of reading the payout, subscribe an endpoint to payout.disbursed, payout.failed and the other payout.* events. When Jane’s payout leaves, your endpoint receives:
The same $500.00 USD has left for Jane. amount is "500.00" because webhooks carry amounts in major units, where the API’s amount_minor is 50000.

​
Handle a payout that fails

If the payout reads failed instead of disbursed, the money did not leave, unless failure_code is indeterminate. failure_code says why and replaceable says whether you can try again. Fix what the code names, then create a new payout with replaces_payout_id set to this one’s ID. Payout events lists every code and its recovery.