Environments

Choose where each call reads and writes, use your sandbox test money, and know what sandbox can’t exercise before you rely on it. For developers deciding where to build and test an integration before going live.

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

Choose an environment

Every Business operates in two parallel environments at once:

Sandbox: no money moves and no fees accrue. Open to every Business once its email is verified and its business profile is submitted. Every sandbox payout stops at disbursed. See Know the limits of sandbox.
Production: money moves. Open once your Business’s verification (KYB) is approved. See Go live.

Both environments hold the same kinds of data (Beneficiaries, destinations, payouts, webhook endpoints) as two disjoint sets. Nothing you create in sandbox exists in production, and vice versa.

Select the environment with the credential

There is no environment parameter anywhere in the API. The environment comes from the credential making the call:

ck_sandbox_a3f9bc12_<secret>      →  every call reads and writes sandbox data
ck_production_a3f9bc12_<secret>   →  every call reads and writes production data

What a key can see is covered in Scope a key to one Business and environment.

Test the whole payout loop in sandbox

Sandbox runs the complete payout loop: funding, Beneficiary onboarding, approval, dispatch, disbursement and webhooks. Two things work differently by design:

Your balance is test money. See Use your sandbox test money.
Beneficiary-facing emails carry a sandbox banner.

Build and test your whole integration in sandbox first; going live is then a credential swap plus a real funding path, not a rewrite.

Use your sandbox test money

Once you create your account and submit your business profile, your sandbox has $1,000,000.00 USD of test money. Sandbox payouts never draw it down. Read the balance with GET /v1/funding/account:

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

{
  "currency": "USD",
  "available_balance_minor": 100000000,
  "total_balance_minor": 100000000
}

Your sandbox holds $1,000,000.00 USD; available_balance_minor is 100000000 because amounts are in minor units. Set a different balance with POST /v1/business/funding-account/sandbox-balance, using a key with the business_admin role:

curl -X POST https://api.usecleff.com/v1/business/funding-account/sandbox-balance \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "available_balance_minor": 5000000,
    "total_balance_minor": 5000000
  }'

Your sandbox now holds $50,000.00 USD. The call sets the balance rather than adding to it, so setting 0 brings SANDBOX_WALLET_UNFUNDED back: sandbox payout creation is refused until you set a balance above zero again. Sent payouts never draw the sandbox balance down. The top-up works only in sandbox: a production key is refused with SANDBOX_ONLY, and a production balance changes only through real deposits to your Cleff Account.

Know the limits of sandbox

Some production behaviour has no sandbox equivalent. Plan to see it for the first time in production, with a small payout:

In sandbox	So in production
There is no card destination. A collection link sent from sandbox collects a bank account, even when the Beneficiary would rather use a card.	Card payouts are exercised only here, once your Business is approved for card payouts. Send a first small one before opening the volume.
Every payout succeeds and stops at `disbursed`.	`payout.delivered`, `payout.settled`, `payout.canceled` and `payout.returned` arrive for the first time. Subscribe to them before you go live.
The provider accepts every Beneficiary and bank account.	The provider can refuse one: `beneficiary.enrollment_rejected` arrives, and payouts to that Beneficiary are refused with `BENEFICIARY_ENROLLMENT_FAILED` until it accepts one of their bank accounts. Subscribe to it and read `enrollment_failure_detail`.
Creating a payout needs a balance above zero, and sent payouts never draw it down.	Creating a payout doesn’t check your balance; a shortfall surfaces when it is sent. Read your balance with `GET /v1/funding/account` before a run.

Next steps

Authentication

Get an API key and send it with every request.

Idempotency

Retry a request safely after a timeout or a 5xx.

Errors

What each error code means and how to fix it.

Webhooks

Receive signed payout and beneficiary events instead of polling.

Get started

Essentials

Beneficiaries

Payouts

Choose an environment

Select the environment with the credential

Test the whole payout loop in sandbox

Use your sandbox test money

Know the limits of sandbox

Next steps

Authentication

Idempotency

Errors

Webhooks

​Choose an environment

​Select the environment with the credential

​Test the whole payout loop in sandbox

​Use your sandbox test money

​Know the limits of sandbox

​Next steps

Authentication

Idempotency

Errors

Webhooks

Choose an environment

Select the environment with the credential

Test the whole payout loop in sandbox

Use your sandbox test money

Know the limits of sandbox

Next steps