Skip to main content

​
Overview

Every ZBD project includes a sandbox environment for testing the ZBD Widget integration end-to-end. Sandbox mode simulates the entire flow — funding users, initiating cashouts, and receiving webhooks — without moving real money through ACH or requiring real identity verification.
Sandbox API keys are separate from production keys. Make sure you’re using the right key for the right environment.

​
What Sandbox Does

FeatureSandboxProduction
User creationCreates real user recordsSame
Balance fundingCredits test balance (no real money)Debits partner’s CRB pool
KYC / IdentitySkipped — users can cashout without OnfidoRequired for bank cashouts
Bank linking (Plaid)Full Plaid sandbox flowReal bank connections
ACH payoutSimulated — completes instantly, no real transferReal ACH via banking partner
WebhooksFires normally to your webhook_urlSame
Widget UIIdentical to productionSame

​
Getting Started

​
1. Get Your Sandbox API Key

In the ZBD Developer Dashboard, navigate to your project’s API tab and copy the Sandbox key.
Never use sandbox keys in production or production keys in sandbox. The endpoints will reject mismatched keys.

​
2. Create a Test User

curl -X POST https://api.zebedee.io/api/v1/cashout/users \
  -H "apikey: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "test-player-1",
    "email": "test@yourcompany.com"
  }'

​
3. Fund the Test User

curl -X POST https://api.zebedee.io/v1/cashout/funding-transfers \
  -H "apikey: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zbd_user_id": "USER_ID_FROM_STEP_2",
    "amount": 5000,
    "currency": "USD",
    "idempotency_key": "UNIQUE_UUID",
    "description": "Test reward"
  }'
In sandbox, funding transfers don’t debit a real pool. The balance is credited for testing purposes.

​
4. Create a Widget Session

curl -X POST https://api.zebedee.io/api/v1/cashout-widget \
  -H "apikey: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@yourcompany.com",
    "webhook_url": "https://your-server.com/zbd/webhooks"
  }'

​
5. Open the Widget

Embed the returned widget_url in an iframe. The widget behaves identically to production — same UI, same flows — but cashouts complete without real bank transfers.

​
Sandbox Webhooks

Sandbox webhooks fire to your webhook_url with the same payload structure as production: 
{
  "event": "ZBD_WIDGET.V1.CASHOUT.INITIATED",
  "timestamp": "2026-06-01T12:00:00.000Z",
  "data": {
    "payout_id": "f4ba94c1-...",
    "user_account_id": "4ac4fd8a-...",
    "amount": "50.00",
    "currency": "USD",
    "payment_method": "ach",
    "status": "initiated",
    "reference_id": "test-player-1",
    "fee_amount": "2.50"
  }
}
In sandbox, the COMPLETED webhook fires shortly after INITIATED since there’s no real ACH settlement delay.

​
Sandbox Limitations

  • No real ACH transfers — cashouts are simulated and settle instantly
  • No real KYC — identity verification is bypassed
  • Plaid sandbox banks — use Plaid’s sandbox credentials for bank linking
  • Sandbox balance is not real money — cannot be withdrawn to a real bank account

​
Moving to Production

When you’re ready to go live:
1

Complete Testing

Verify all flows work: funding, cashout, webhooks, error handling
2

Register Webhook URL

Set your production webhook endpoint in the dashboard
3

Switch API Key

Replace your sandbox API key with the production key
4

Fund Your Pool

Contact ZBD to fund your production CRB pool
5

Go Live

Deploy and monitor your first real cashouts
Production cashouts move real money. Make sure your webhook handler correctly processes COMPLETED and FAILED events before going live.