Skip to main content
This walkthrough takes a brand-new account to a disbursed sandbox payout. Everything runs against the sandbox environment: provider calls hit mock implementations, no money moves, and nothing here requires review or approval from Cleff. You need an email address, a terminal with curl, and nothing else.
1

Create your account

Sign up at app.usecleff.com/signup. The two-step wizard creates your user account and your Business (labelled Organization in the dashboard). Verify the email you receive, then sign in.Sandbox access is granted immediately on email verification. Production stays locked until your business completes verification; see Go live when you get there.
2

Complete your business profile

In the dashboard, fill in your company profile under Settings → Company and submit it. A complete profile provisions your sandbox wallet with $1,000,000 of test money; until then, payout creation is refused with SANDBOX_WALLET_UNFUNDED. (The same profile later becomes your verification dossier for going live, so nothing here is throwaway work.)
3

Mint a sandbox API key

In the dashboard, open Settings → API keys and create a key. The plaintext key is shown exactly once: Cleff stores only a verifier and cannot show it again. Export it for the rest of this walkthrough:
The ck_sandbox_ prefix is load-bearing: this key only ever sees sandbox data. Authentication covers the key format and rotation.
4

Confirm your sandbox balance

Payouts draw from your Cleff Account. The test money from your submitted profile lands moments after the submit returns, so confirm it is there:
Poll until available_balance_minor is above zero. Amounts are in minor units everywhere in the API. If you ever want a different balance, the sandbox top-up sets it directly; that endpoint is rejected outside sandbox.
5

Create a Beneficiary

A Beneficiary is a person or business you pay. Passing acknowledged: true attests that your Business has independently verified their identity, which moves them straight to compliant, the state payout creation requires. (See Beneficiaries & compliance for what that attestation means and for the invite flow where beneficiaries submit their own details.)
Capture beneficiary.id from the response:
6

Register their bank account

Payouts name an explicit destination account. Because the Beneficiary is already compliant, the account comes back verified immediately; a routing code that passes Cleff’s format checks makes it validated. Both together set payout_usable: true, the one flag that matters.
Capture bank_account.id:
Identifiers are masked to last4 in every read; the full account number is never serialized back.
7

Create the payout

The payout is created in pending_approval; nothing moves until a Decision approves it. The idempotency_key makes this call safe to retry: replaying it within 24 hours returns the original payout with HTTP 200 instead of creating a second one.
8

Approve it

Every payout passes an approval gate before dispatch. Approve yours (the decision_id is a caller-supplied ULID that makes the decision idempotent):
Approval enqueues the disbursement; the dispatch itself runs asynchronously.
9

Watch it disburse

Poll the payout and watch state advance from approved to disbursed as the sandbox provider confirms the disbursement:
That is the whole loop: fund → register → create → approve → disburse. In production the only differences are real providers, real money, and a funded account you cannot top up by API.

​
Where to go next

Listen instead of polling

Register a webhook endpoint and receive signed payout lifecycle events.

Invite beneficiaries to self-onboard

Send secure collection links so beneficiaries submit their own bank details.

Understand the lifecycle

Every payout state, the headroom check, and what happens on failure or return.

Go live

The path from sandbox to production: verification, pricing, and a production key.