ZBD Widget

Overview

The ZBD Widget is an embeddable iframe that handles the full cashout flow for your users — identity verification (KYC), bank account linking (Plaid), and ACH payouts. Your backend handles user creation, session minting, and balance funding; the widget handles everything else.

Prerequisites

Before integrating:

Make sure you already have a ZBD Developer Dashboard account and a project.
Copy the project API key from the project’s API section.
Open the Widget tab in the Developer Dashboard to configure sandbox balance and webhook settings.
If the Widget tab is not available yet, contact ZBD support to enable it for your project.

After that, fund the sandbox account before you try to cash out.

Quick Start

To get sandbox running quickly, start with the sandbox guide:

Create a sandbox user.
Fund the sandbox user.
Create a widget session.
Embed the returned widget_url in your frontend.
Listen for widget events and webhook deliveries.

Integration Flow

Create User        POST /api/v1/widget/users                (your server → ZBD API)
Fund User          POST /api/v1/widget/users/fund           (your server → ZBD API)
Deplete User       POST /api/v1/widget/users/deplete        (your server → ZBD API)
Get Balance        GET /api/v1/widget/users/{userId}/balance (your server → ZBD API)
Create Session     POST /api/v1/widget/users/session        (your server → ZBD API)
Embed Widget       <iframe src="{widget_url}" />            (your frontend)
Listen for Events  window.addEventListener("message", ...)  (your frontend)

Use POST /api/v1/widget/users/deplete when your server needs to debit points back from a widget user’s point balance.

Events

The ZBD Widget emits browser events to your frontend and server webhooks to your backend.

Browser Events

Handle iframe callbacks in your frontend.

Server Webhooks

Process signed backend webhook deliveries.

Authentication

Widget endpoints use two auth patterns:

Context	Auth	Header
Your server → ZBD	Publisher API key	`apikey: YOUR_API_KEY`
Widget iframe → ZBD	Session JWT (automatic)	`Authorization: Bearer {session_token}`

Never expose your publisher API key in the browser. Steps 1–3 must happen on your server.

After creating a session, load the returned widget_url in your client. Your backend should create the session; your game or web client only receives the widget_url.

Web
Unity
Unreal

<iframe
  src="https://widget.zbd.gg/?session_token=eyJhbGci..."
  style="width: 100%; height: 600px; border: none;"
  allow="camera; microphone"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-downloads"
></iframe>

Use a native WebView package for your Unity target and load the widget_url returned by your backend.

using UnityEngine;

public class ZbdWidgetLauncher : MonoBehaviour
{
    [SerializeField] private GameObject webViewContainer;

    public void OpenWidget(string widgetUrl)
    {
        // Replace this with your Unity WebView package API.
        var webView = webViewContainer.GetComponent<IWebView>();
        webView.LoadUrl(widgetUrl);
        webView.SetVisible(true);
    }
}

public interface IWebView
{
    void LoadUrl(string url);
    void SetVisible(bool visible);
}

Enable Unreal’s Web Browser plugin, add a Web Browser widget to your UMG screen, and load the widget_url returned by your backend.

#include "Components/WebBrowser.h"

void UCashoutScreen::OpenZbdWidget(const FString& WidgetUrl)
{
    if (ZbdWidgetBrowser)
    {
        ZbdWidgetBrowser->LoadURL(WidgetUrl);
    }
}

Allow document downloads. The widget lets users download documents (disclosure PDFs, cashout receipts/statements). Browsers only permit a framed page to start a download if the iframe explicitly allows it. If you apply a sandbox attribute — as in the example above — it must include allow-downloads (alongside allow-scripts allow-same-origin allow-forms allow-popups). Without allow-downloads, the browser blocks the in-frame download and the widget falls back to opening the document in a new browser tab. If you do not set a sandbox attribute at all, downloads work by default.

Embed Parameters

Pass these as URL query parameters on the widget URL:

Parameter	Required	Description
`session_token`	Yes	JWT from Create Session
`flow`	No	`cashout` (default), `kyc`, `add-method`
`theme`	No	`zbd-default`, `zbd-light`
`embed`	No	`true` for chrome-less mode (no header/footer)
`component`	No	`balance`, `history`, `method-picker` for standalone components

Overview

Events

API Reference

Testing

Overview

Prerequisites

Quick Start

Integration Flow

Events

Browser Events

Server Webhooks

Authentication

Embedding the Widget

Embed Parameters

​Overview

​Prerequisites

​Quick Start

​Integration Flow

​Events

Browser Events

Server Webhooks

​Authentication

​Embedding the Widget

​Embed Parameters

Overview

Prerequisites

Quick Start

Integration Flow

Events

Authentication

Embedding the Widget

Embed Parameters