Skip to content

widget.mdx

Latest commit

 

History

History
143 lines (109 loc) · 5.4 KB

widget.mdx

File metadata and controls

143 lines (109 loc) · 5.4 KB
Raw
title ZBD Widget
description Embed a hosted cashout experience so your users can withdraw earned balances to bank accounts, Cash App, and more.

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:

  1. Make sure you already have a ZBD Developer Dashboard account and a project.
  2. Copy the project API key from the project's API section.
  3. Open the Widget tab in the Developer Dashboard to configure sandbox balance and webhook settings.
  4. 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:

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

Integration Flow

1. Create User        POST /api/v1/widget/users                (your server → ZBD API)
2. Fund User          POST /api/v1/widget/users/fund           (your server → ZBD API)
3. Deplete User       POST /api/v1/widget/users/deplete        (your server → ZBD API)
4. Get Balance        GET /api/v1/widget/users/{userId}/balance (your server → ZBD API)
5. Create Session     POST /api/v1/widget/users/session        (your server → ZBD API)
6. Embed Widget       <iframe src="{widget_url}" />            (your frontend)
7. 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.

Handle iframe callbacks in your frontend. 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.

Embedding the Widget

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.

```html <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. 
```csharp
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. 
```cpp
#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