ZBD Widget

Overview

The ZBD Widget is an embeddable iframe that runs the cashout experience for your users — OTP verification, identity verification, bank account linking, and bank payouts. Your backend creates widget users, funds their point balances, creates sessions, and records Electronic Funds Transfer disclosure acceptance when offering ACH cashout.

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.

Terms and disclosures

For widget ACH cashout, your application must present and record acceptance of the latest Electronic Funds Transfer disclosure (type 6). The widget does not render this document or collect acceptance on the publisher’s behalf. ACH cashout is rejected until the current type 6 version has been accepted. Disclosure types 1 through 5 are not prerequisites for widget session creation or ACH cashout and can be ignored for this integration. Your contract or other ZBD services may impose separate legal requirements.

Country availability

The widget uses the country resolved from the user’s IP before identity verification. After identity verification, it uses the user’s verified residential country to select the available bank rail.

USD bank cashout

USD bank cashout (ACH) is available only in the United States.

EUR bank cashout

EUR bank cashout (SCT) is available in Austria, Belgium, Denmark, Estonia, Finland, France, Germany, Italy, Latvia, Lithuania, the Netherlands, Poland, Portugal, Spain, and Sweden. SCT is not available in other countries, including Bulgaria, Croatia, Cyprus, Czechia, Greece, Hungary, Ireland, Luxembourg, Malta, Romania, Slovakia, Slovenia, and Switzerland.

Restricted locations

The widget is not supported for users in Cuba, Iran, North Korea, or Syria.

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)
Reverse a Fund     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 to reverse an available balance that your server previously funded, such as when a reward is canceled.

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

Terms and disclosures

Country availability

USD bank cashout

EUR bank cashout

Restricted locations

Integration Flow

Events

Browser Events

Server Webhooks

Authentication

Embedding the Widget

Embed Parameters

​Overview

​Prerequisites

​Quick Start

​Terms and disclosures

​Country availability

​USD bank cashout

​EUR bank cashout

​Restricted locations

​Integration Flow

​Events

Browser Events

Server Webhooks

​Authentication

​Embedding the Widget

​Embed Parameters

Overview

Prerequisites

Quick Start

Terms and disclosures

Country availability

USD bank cashout

EUR bank cashout

Restricted locations

Integration Flow

Events

Authentication

Embedding the Widget

Embed Parameters