Going live

A checklist to move from the sandbox to real payouts with confidence.

You've built and tested your integration against ck_test_. Going live is mostly swapping the key — but a few things must be in place first. Work through this checklist before your first real payout.

1. Complete KYB

Live mode requires a verified business. Submit KYB (legal details, beneficial owners, documents) from the Business dashboard or POST /v1/kyb, and wait for verified. Until then, live keys and live payouts return kyb_required. See Compliance & screening.

bash
curl https://api.caiboglobal.com/v1/organization \
  -H "X-API-Key: $CAIBO_API_KEY"   # confirm "kyb_status": "verified"

2. Create a live API key

Once verified, create a ck_live_ key with only the scopes your service needs. Store it in your secret manager — the full key is shown once. Keep it server-side only. See Authentication.

3. Register a production webhook endpoint

Register your production HTTPS endpoint with a live key, subscribe to the events you handle, and store the signing secret. Confirm end-to-end that:

  • Your endpoint verifies the signature and rejects stale timestamps (> 5 min).
  • It reads the raw body for verification.
  • It responds 2xx quickly and processes asynchronously.
  • Handling is idempotent (dedupe on event + payout id).

See Webhooks.

4. Review your limits

Read GET /v1/organization and confirm the per-payout, daily, and monthly limits match your expected volume. If your launch needs more headroom, request higher limits before you start.

5. Handle pending_approval

Decide how large payouts (above your auto-approval limit) get approved, and make sure someone can approve them from the Business dashboard. Your integration should treat pending_approval as a hold and wait for the eventual completion or failure webhook. See Payout lifecycle.

6. Make error and retry handling production-grade

  • Retry 429 and 5xx with exponential backoff; reuse the same idempotency key on payout retries.
  • Route blocked, kyb_required, and limit_exceeded to a human — never auto-retry.
  • Log request_id on every failure.

See Errors.

7. Fund your balance

Live payouts draw on your organization's balance. A payout above your available balance returns insufficient_balance. Make sure the balance is funded for the asset you're paying out.

8. Monitor

  • Reconcile regularly: list payouts and compare against your own records.
  • Alert on failed, blocked, and insufficient_balance.
  • Watch webhook health — track deliveries your endpoint rejected so none are silently missed.
  • Track balances so payouts never stall on funding.

Launch checklist

  • ☐ KYB verified
  • ☐ Live API key created, stored in a secret manager, scoped minimally
  • ☐ Production webhook endpoint registered, verifying signatures, idempotent
  • ☐ Limits reviewed for launch volume
  • ☐ pending_approval approval path in place
  • ☐ Retry/backoff and error routing implemented
  • ☐ Balance funded
  • ☐ Monitoring, alerting, and reconciliation live

When every box is checked, send your first live payout — start small, confirm the webhook and the on-chain tx_hash, then scale up.