Sandbox

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.

Sandbox API base URL: https://sandbox-api.zbdpay.com

What Sandbox Does

Feature	Sandbox	Production
User creation	Creates sandbox-scoped widget users	Creates production widget users
Balance funding	Credits test reward balance; no live pool is debited	Transfers publisher points from your live pool
KYC / Identity	Controlled through sandbox KYC status helpers; no live Onfido review	Required for bank cashouts
Bank linking (Plaid)	Full Plaid sandbox flow	Real bank connections
ACH payout	Simulated when sandbox bypass is enabled; no real transfer	Real ACH via banking partner
Disclosures	Same status and acceptance model; bypass settings may skip cashout disclosure checks	Required disclosures can block cashout until accepted
Webhooks	Fire normally to your `webhook_url`	Same
Widget UI	Identical to production	Same

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://sandbox-api.zbdpay.com/api/v1/cashout/sandbox/users \
  -H "apikey: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "test-player-1",
    "email": "test@yourcompany.com"
  }'

Sandbox user creation uses a sandbox-only endpoint. Use the returned data.id as zbd_user_id when funding the user and as the user ID when setting KYC status. Use POST /api/v1/widget/users only for production widget users.

3. Fund the Test User

curl -X POST https://sandbox-api.zbdpay.com/api/v1/widget/users/fund \
  -H "apikey: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "USER_ID_FROM_STEP_2",
    "amount": 5000,
    "currency": "USDZ",
    "idempotency_key": "UNIQUE_UUID"
  }'

In sandbox, funding transfers don’t debit a real pool. The balance is credited for testing purposes.

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

Embed the returned widget_url in an iframe. In sandbox, the URL should point at https://widget.sandbox.zbd.gg. The widget behaves identically to production — same UI, same flows — but cashouts complete without real bank transfers.

When you reach bank linking in sandbox, you can use the Plaid sandbox institution Platypus First Bank with the credentials user_good / pass_good. If Plaid asks for a phone number step, you can bypass it in the sandbox flow.

When you reach KYC in sandbox, use a US address so the approval path can complete successfully.

Sandbox Controls

Use these sandbox-only controls on https://sandbox-api.zbdpay.com with apikey: YOUR_SANDBOX_API_KEY to put a test user or monetary account into a known state before opening the widget. For user rewards, use POST /api/v1/widget/users/fund and POST /api/v1/widget/users/deplete. The monetary-account helpers below are for state setup when you already have the monetary account ID.

Control	Endpoint	Request body
Create sandbox user	`POST /api/v1/cashout/sandbox/users`	`{ "reference_id": "test-player-1", "email": "test@yourcompany.com" }`
Set user KYC status	`POST /api/v1/principal-accounts/{zbd_user_id}/kyc-status`	`{ "status": "approved", "country_code": "US" }`
Add sandbox balance	`POST /api/v1/monetary-accounts/{monetary_account_id}/fund`	`{ "amount": 5000 }`
Remove sandbox balance	`POST /api/v1/monetary-accounts/{monetary_account_id}/deplete`	`{ "amount": 5000 }`

KYC status must be approved, rejected, or processing. Include country_code when setting approved. Balance helper amounts use currency minor units. For USD, 5000 means $50.00.

Disclosure acceptance can be tested in sandbox with the same flow as production. If you need to verify that cashout is blocked by a missing disclosure, make sure your sandbox setup is not using a bypass mode that skips the disclosure gate.

ACH return-code simulation and explicit payout failure-mode controls are still being wired for sandbox. Until those controls are available, use the webhook examples to prepare your handler for cashout.failed and cashout.returned events.

Sandbox Webhooks

Sandbox webhooks fire to your webhook_url with the same payload structure as production:

{
  "event_id": "evt_sandbox_123",
  "event_type": "cashout.initiated",
  "user_reference_id": "test-player-1",
  "amount_cents": 5000,
  "status": "initiated",
  "occurred_at": "2026-06-01T12:00:00Z"
}

In sandbox, the cashout.completed webhook can fire shortly after cashout.initiated since there’s no real ACH settlement delay. See Server Webhooks for the full event reference.

Moving to Production

When you’re ready to go live:

Complete Testing

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

Set your production webhook endpoint in the dashboard

Switch API Key

Replace your sandbox API key with the production key

Fund Your Pool

Contact ZBD to fund your production CRB pool

Go Live

Deploy and monitor your first real cashouts

Production cashouts move real money. Make sure your webhook handler correctly processes cashout.completed, cashout.failed, and cashout.returned events before going live.

Overview

Events

API Reference

Testing

Overview

What Sandbox Does

Getting Started

1. Get Your Sandbox API Key

2. Create a Test User

3. Fund the Test User

4. Create a Widget Session

5. Open the Widget

Sandbox Controls

Sandbox Webhooks

Moving to Production

​Overview

​What Sandbox Does

​Getting Started

​1. Get Your Sandbox API Key

​2. Create a Test User

​3. Fund the Test User

​4. Create a Widget Session

​5. Open the Widget

​Sandbox Controls

​Sandbox Webhooks

​Moving to Production

Overview

What Sandbox Does

Getting Started

1. Get Your Sandbox API Key

2. Create a Test User

3. Fund the Test User

4. Create a Widget Session

5. Open the Widget

Sandbox Controls

Sandbox Webhooks

Moving to Production