> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbdpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding the Widget

> Add ZBD's hosted flows for identity verification, payment methods, balances, and cash out to your game.

The widget runs the steps where ZBD collects something from the player, and gives you ready-made views of their balance and history. You embed it in your game and choose which flows to use and where they appear.

## Flows

| Flow | `flows` value | What it does |
| - | - | - |
| Identity verification | `kyc` | Verifies the player. Can run on its own, for example at signup. |
| Payment method selection | `payment_methods` | The player chooses how to be paid from the methods available in their country, with each method's fee shown. Bank accounts are linked here, and methods that need no linking, like gift cards, are chosen here too. |
| Disclosures | `disclosures` | The player accepts disclosures a cash out needs, such as the Electronic Funds Transfer agreement for US bank payouts. |
| Cash out | `cashout` | The player converts their cashable balance and cashes out. This is the only way to cash out. |

ZBD collects tax information within these flows when a cash out requires it.

If a player opens the cash out flow before they've verified or chosen a payment method, the widget takes them through those steps first.

## Embedding a flow

<Steps>
  <Step title="Create a session with the flows you need">
    Call [Create a Session](/embedded-accounts/apis/create-session) from your server with the `flows` this session can open, for example `["kyc"]` at signup. Your API key never reaches the game client, and the player can't open a flow you didn't list. The response includes a `widget_url`.
  </Step>

  <Step title="Load the widget">
    Load the URL in an iframe or WebView at the point in your product where the flow should appear. See [Code examples](#code-examples).
  </Step>

  <Step title="Listen for events">
    Your frontend receives [browser events](/embedded-accounts/browser-events) as the player moves through the flow, for example when they finish verification or add a payment method. Cash out status changes reach your backend by [webhook](/embedded-accounts/apis/webhook-events).
  </Step>
</Steps>

One session can open any of the flows you listed without the player signing in again. For example, a session with `["kyc", "cashout"]` can verify a player and take them straight into their first cash out.

## Embed parameters

These control how the widget looks. Add them as query parameters on the `widget_url` returned by Create a Session. Don't build the widget URL or hostname yourself, and choose flows on the session, not in the URL.

| Parameter | Values | What it does |
| - | - | - |
| `theme` | `zbd-default`, `zbd-light` | Sets the widget theme |
| `embed` | `true` | Hides the widget's header and footer, so it sits inside your own UI |
| `component` | `balance`, `history`, `method-picker` | Shows a single component on its own: the player's balances, their transaction history, or the payment method picker |

## Code examples

<Tabs>
  <Tab title="Web">
    ```html theme={null}
    <iframe
      id="zbd-widget"
      src="{widget_url}"
      style="width: 100%; height: 600px; border: none;"
      allow="camera; microphone"
      sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-downloads"
    ></iframe>
    ```
  </Tab>

  <Tab title="Unreal">
    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 theme={null}
    #include "Components/WebBrowser.h"

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

  <Tab title="Unity">
    Use a native WebView package for your Unity target and load the `widget_url` returned by your backend.

    ```csharp theme={null}
    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);
    }
    ```
  </Tab>
</Tabs>

The widget needs camera and microphone access for identity verification, so keep the `allow` attribute.

<Warning>
  **Allow downloads.** Players can download documents from the widget, such as disclosures and cash out receipts. If you set a `sandbox` attribute on the iframe, it has to include `allow-downloads`, as in the example above. Without it, the browser blocks the download and the widget opens the document in a new tab instead. If you don't set a `sandbox` attribute, downloads work by default.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.