curl -X POST https://api.zbdpay.com/api/v1/widget-sessions \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"flows": ["kyc", "payment_methods"]
}'
{
"success": true,
"message": "Session created.",
"data": {
"session_token": "eyJhbGciOiJSUzI1NiIs...",
"widget_url": "https://widget.zbd.gg/?session_token=eyJhbGci...",
"flows": ["kyc", "payment_methods"],
"expires_at": "2026-10-01T22:00:00Z"
},
"error": null
}
Users
Create a Session
Create a widget session for a user, with the flows it can open.
POST
/
api
/
v1
/
widget-sessions
curl -X POST https://api.zbdpay.com/api/v1/widget-sessions \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"flows": ["kyc", "payment_methods"]
}'
{
"success": true,
"message": "Session created.",
"data": {
"session_token": "eyJhbGciOiJSUzI1NiIs...",
"widget_url": "https://widget.zbd.gg/?session_token=eyJhbGci...",
"flows": ["kyc", "payment_methods"],
"expires_at": "2026-10-01T22:00:00Z"
},
"error": null
}
Returns a
When the session is close to expiring, the widget asks your page for a new one. See Refreshing a session.
widget_url you load in an iframe or WebView. The flows you list are the only ones the session can open, and they’re carried in the signed session token, so they can’t be changed from the browser.
The user has to exist first. Create them with Create a User.
Configuration
Header Parameters
Body Parameters
The flows this session can open:
kyc (identity verification), payment_methods (payment method selection), disclosures, and cashout. cashout is only available where ZBD holds the user’s balance.curl -X POST https://api.zbdpay.com/api/v1/widget-sessions \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"flows": ["kyc", "payment_methods"]
}'
{
"success": true,
"message": "Session created.",
"data": {
"session_token": "eyJhbGciOiJSUzI1NiIs...",
"widget_url": "https://widget.zbd.gg/?session_token=eyJhbGci...",
"flows": ["kyc", "payment_methods"],
"expires_at": "2026-10-01T22:00:00Z"
},
"error": null
}
Response
The session is indata.
The signed token for this session. It’s already in
widget_url, so you only need it on its own when the widget asks your page for a new session.The URL to load in an iframe or WebView. Load it as it comes back, and add embed parameters if you need them.
Errors
| HTTP | code | When |
|---|---|---|
400 | validation_failed | flows is empty or contains an unknown flow |
401 | unauthorized | The API key is missing or invalid |
403 | feature_not_enabled | A requested flow isn’t available for your program, for example cashout when you track balances yourself |
404 | user_not_found | The user doesn’t exist under your key |
Was this page helpful?