Quickstart: send your first payout

Send your first sandbox payout, from a brand-new account to a disbursed payout. For developers who want to see the whole loop before wiring Cleff into their product. Everything runs against the sandbox environment: no money moves, and nothing here needs review or approval from Cleff.

Agents: fetch this page as plain markdown at https://docs.usecleff.com/quickstart.md.

You need an email address, a terminal with curl, and nothing else.

Create your account

Sign up at app.usecleff.com/signup. The three-step wizard creates your user account and your Business (labelled Organization in the wizard and Company in the dashboard). Verify the email you receive, then sign in.Once your email is verified, the dashboard opens on your business profile and stays there until you submit it, which is the next step. Production stays locked until your Business completes verification; see Go live when you get there.

Complete your business profile

In the dashboard, fill in your company profile under Settings → Company and submit it. Submitting takes you to the dashboard home, and your sandbox now has $1,000,000.00 USD of test money. The same profile later becomes your verification dossier for going live, so nothing here is throwaway work.

Mint a sandbox API key

In the dashboard, open Settings → API keys and create a key. The plaintext key is shown exactly once: Cleff cannot show it again. Export it for the rest of this walkthrough:

export CLEFF_API_KEY="ck_sandbox_..."

Authentication covers the key format and rotation.

Create a Beneficiary

A Beneficiary (the payee) 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. Beneficiaries & compliance explains what that attestation means.

curl -X POST https://api.usecleff.com/v1/beneficiaries \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_type": "person",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "country_of_residence": "US",
    "acknowledged": true
  }'

Capture beneficiary.id from the response:

export BEN_ID="<beneficiary.id>"

Give Jane a destination

A payout goes to a destination: somewhere the Beneficiary can be paid. Jane has none yet, so register one on her behalf. Here it is a US bank account:

curl -X POST https://api.usecleff.com/v1/beneficiaries/$BEN_ID/bank-accounts \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_holder_name": "Jane Doe",
    "country": "US",
    "currency": "USD",
    "account_number": "000123456789",
    "routing_code": "021000021"
  }'

Check that payout_usable is true in the response. That is the one flag that says a payout can reach this destination. Account numbers are masked to last4 in every response.

Create the payout

Mint an idempotency key for this payout. It is what makes the call safe to retry, so keep it for as long as you might resend the request:

export IDEMPOTENCY_KEY=$(uuidgen)

The request names who to pay and how much, but not where:

curl -X POST https://api.usecleff.com/v1/payouts \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "beneficiary_id": "'$BEN_ID'",
    "amount_minor": 50000,
    "currency": "USD",
    "purpose_of_payment": "other",
    "external_ref": "INVOICE-2026-0001"
  }'

{
  "payout": {
    "id": "5f0c1f6e-8f4b-4b0e-9f6d-2a7c9d1e3b42",
    "state": "pending_approval",
    "status": "needs_approval",
    "beneficiary_id": "…",
    "destination_id": "…",
    "destination_kind": "bank",
    "amount_minor": 50000,
    "currency": "USD",
    "external_ref": "INVOICE-2026-0001"
  }
}

Jane Doe is owed $500.00 USD; amount_minor is 50000 because amounts are in minor units. A payout goes to the destination the Beneficiary declared. Jane has not declared one, so it goes to her only payout-usable destination, the one you just registered; destination_id names it.

Once a Beneficiary declares a destination, a payout that names none goes there; destination_id names any other of their destinations to pay that one instead. A Beneficiary with several payout-usable destinations and none declared needs destination_id to say which one; without it the payout is refused with BANK_ACCOUNT_AMBIGUOUS.

The payout starts in pending_approval; nothing moves until it is approved. Re-running this curl with the same key within 24 hours returns the original payout with HTTP 200 instead of creating a second one; changing the amount or any other detail under the same key is refused with IDEMPOTENCY_CONFLICT. See Idempotency.

export PAYOUT_ID="<payout.id>"

Approve it

Every payout passes an approval gate before it is sent. Approve yours. The decision_id is a ULID you supply, which makes the approval safe to retry:

curl -X POST https://api.usecleff.com/v1/payouts/$PAYOUT_ID/approve \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "01K4Q6H8Z3TJN0V1B2C3D4E5F6"
  }'

Approval queues the payout to be sent; sending happens asynchronously.

Watch it disburse

Poll the payout and watch status move from processing to in_transit once the provider confirms the money has left:

curl https://api.usecleff.com/v1/payouts/$PAYOUT_ID \
  -H "Authorization: Bearer $CLEFF_API_KEY"

{
  "id": "5f0c1f6e-8f4b-4b0e-9f6d-2a7c9d1e3b42",
  "state": "disbursed",
  "status": "in_transit",
  "delivered_at": null,
  "destination_id": "…",
  "destination_kind": "bank",
  "amount_minor": 50000,
  "currency": "USD",
  "external_ref": "INVOICE-2026-0001"
}

$500.00 USD has left your Cleff Account for Jane’s destination.That is the whole loop: add a Beneficiary and a destination, create, approve, disburse. In production the only differences are real providers and real money.

Next steps

Using the dashboard

What your operations team can do without touching the API.

Go live

Verify your Business, fund your Cleff Account and send real payouts.

Use with AI tools

Point your coding assistant at these docs as plain markdown.

Get started

Essentials

Beneficiaries

Payouts

Quickstart: send your first payout

Next steps

Using the dashboard

Go live

Use with AI tools

​Next steps

Using the dashboard

Go live

Use with AI tools

Next steps