Create Session

Mint a widget session and get the embeddable URL.

POST /api/v1/widget/users/session

cURL

curl -X POST https://api.zbdpay.com/api/v1/widget/users/session \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "webhook_url": "https://your-server.com/zbd/webhooks",
    "reference_id": "player-42",
    "metadata": { "source": "your-game" }
  }'

201

{
  "success": true,
  "data": {
    "session_token": "eyJhbGciOiJSUzI1NiIs...",
    "expires_at": "2026-06-01T00:00:00.000Z",
    "widget_url": "https://widget.zbd.gg?session_token=eyJhbGci..."
  }
}

Description

Creates a widget session for a user. Returns a session_token (JWT) and a widget_url that you embed as an iframe. The session is valid for the duration specified in expires_at.

The widget handles OTP email verification, KYC (Onfido), bank linking (Plaid), and cashout initiation internally.

The widget also checks whether the user has any outstanding session disclosures. Cashout-specific disclosures are enforced when a cashout is submitted. See Disclosure Agreements.

Configuration

Header Parameters

apikey · string · required

Your ZBD project API key (production scope).

Content-Type · string

Content Type

Body Parameters

email · string · required

User’s email address. Required when access_token is not supplied.

webhook_url · string

Optional HTTPS server URL to receive widget webhook events.

reference_id · string

Optional publisher reference for the session.

metadata · object

Optional key-value metadata to attach to the session.

access_token · string

Existing access token. When supplied, email is not required and OTP is skipped.

cURL

curl -X POST https://api.zbdpay.com/api/v1/widget/users/session \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "webhook_url": "https://your-server.com/zbd/webhooks",
    "reference_id": "player-42",
    "metadata": { "source": "your-game" }
  }'

201

{
  "success": true,
  "data": {
    "session_token": "eyJhbGciOiJSUzI1NiIs...",
    "expires_at": "2026-06-01T00:00:00.000Z",
    "widget_url": "https://widget.zbd.gg?session_token=eyJhbGci..."
  }
}