Quickstart

Send your first payout in the sandbox. Everything here runs against a ck_test_ key and never moves real money.

This guide takes you from zero to a completed payout in the sandbox. You'll create a payout, watch it settle, and see the webhook that confirms it. No blockchain funds are moved and no KYB is required — ck_test_ keys are a full simulation.

1. Get a test API key

Sign in to the Business dashboard, create your organization, and open API keys → Create key in Test mode. The full key is shown once — copy it now. It looks like this:

bash
ck_test_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Treat the key like a password. Use it only from your backend — never ship it to a browser or commit it to source control. See Authentication.

2. Set your key as an environment variable

bash
export CAIBO_API_KEY="ck_test_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

3. Create a payout

Send a USDC payout on Polygon. The Idempotency-Key header is required on payout creation — pick a unique value per logical payout (a UUID is ideal).

bash
curl https://api.caiboglobal.com/v1/payouts \
  -H "X-API-Key: $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b2f1e0a-7c3d-4a91-9f2e-1a2b3c4d5e6f" \
  -d '{
    "amount": "25.00",
    "currency": "USDC",
    "rail": "stablecoin",
    "destination": { "network": "polygon", "address": "0x1234abcd5678ef901234abcd5678ef9012345678" },
    "metadata": { "invoice_id": "INV-1001" }
  }'

You get back the payout, already moving through its lifecycle:

json
{
  "id": "po_9f8e7d6c5b4a",
  "object": "payout",
  "status": "processing",
  "mode": "test",
  "amount": "25.00",
  "currency": "USDC",
  "rail": "stablecoin",
  "destination": { "network": "polygon", "address": "0x1234abcd5678ef901234abcd5678ef9012345678" },
  "screening_status": "clear",
  "tx_hash": null,
  "metadata": { "invoice_id": "INV-1001" },
  "created_at": "2026-07-23T14:03:00Z"
}

4. Retrieve it

Poll the payout by id until it reaches a terminal state (in the sandbox this is near-instant):

bash
curl https://api.caiboglobal.com/v1/payouts/po_9f8e7d6c5b4a \
  -H "X-API-Key: $CAIBO_API_KEY"
json
{
  "id": "po_9f8e7d6c5b4a",
  "object": "payout",
  "status": "completed",
  "tx_hash": "0xSIMULATED8f3a9c2b1d4e5f60",
  "amount": "25.00",
  "currency": "USDC",
  "created_at": "2026-07-23T14:03:00Z"
}
Polling works, but webhooks are better. Instead of asking "is it done yet?", register an endpoint and let Caibo tell you. See step 6.

5. Check your balance

bash
curl https://api.caiboglobal.com/v1/balances \
  -H "X-API-Key: $CAIBO_API_KEY"

6. Receive a webhook

Register an HTTPS endpoint and subscribe to payout events. Every delivery is signed — you must verify the signature. The full flow, with verification snippets in Node, Python, and Go, is in Webhooks.

bash
curl https://api.caiboglobal.com/v1/webhooks \
  -H "X-API-Key: $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/caibo/webhook",
    "events": ["payout.completed", "payout.failed", "payout.blocked"]
  }'

7. Exercise failure paths

The sandbox has special destination addresses so you can test every branch deterministically. An address ending in 0blocked is blocked by screening; one ending in 0fail fails to broadcast and is refunded:

bash
# This payout will end up "blocked" (screening)
curl https://api.caiboglobal.com/v1/payouts \
  -H "X-API-Key: $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "10.00", "currency": "USDC", "rail": "stablecoin",
    "destination": { "network": "polygon", "address": "0x00000000000000000000000000000000000blocked" }
  }'

See Environments for the full list of sandbox test addresses.

You're integrated

From here: