curl -X POST https://api.zbdpay.com/api/v1/widget/users/session \
-H "apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "player@example.com",
"webhook_url": "https://your-server.com/zbd/webhooks",
"reference_id": "player-42",
"metadata": { "source": "your-game" }
}'
{
"success": true,
"data": {
"session_token": "eyJhbGciOiJSUzI1NiIs...",
"expires_at": "2026-06-01T00:00:00.000Z",
"widget_url": "https://widget.zbd.gg?session_token=eyJhbGci..."
}
}
API Reference
Create Session
Mint a widget session and get the embeddable URL.
POST
/
api
/
v1
/
widget
/
users
/
session
curl -X POST https://api.zbdpay.com/api/v1/widget/users/session \
-H "apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "player@example.com",
"webhook_url": "https://your-server.com/zbd/webhooks",
"reference_id": "player-42",
"metadata": { "source": "your-game" }
}'
{
"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 asession_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, identity verification (Onfido), bank linking (Plaid), and cashout initiation internally.
Widget session creation does not query or enforce disclosure acceptance. It can
report outstanding disclosures as a read-only status, but the widget does not
render documents or collect acceptance. Types 1 through 5 can be ignored for
widget eligibility.
ACH cashout submission is a separate gate. Before an ACH cashout can succeed,
your application must present and record the latest Electronic Funds Transfer
disclosure (type 6). This requirement is enforced only when the ACH cashout is
submitted. See Disclosure Agreements.
Configuration
Header Parameters
string
required
Your ZBD project API key (production scope).
string
Content Type
Body Parameters
string
required
User’s email address. Required when
access_token is not supplied.string
Optional HTTPS server URL to receive widget webhook events.
string
Optional publisher reference for the session.
object
Optional key-value metadata to attach to the session.
string
Existing access token. When supplied,
email is not required and OTP is skipped.curl -X POST https://api.zbdpay.com/api/v1/widget/users/session \
-H "apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "player@example.com",
"webhook_url": "https://your-server.com/zbd/webhooks",
"reference_id": "player-42",
"metadata": { "source": "your-game" }
}'
{
"success": true,
"data": {
"session_token": "eyJhbGciOiJSUzI1NiIs...",
"expires_at": "2026-06-01T00:00:00.000Z",
"widget_url": "https://widget.zbd.gg?session_token=eyJhbGci..."
}
}
Was this page helpful?