Browser Events

Overview

The ZBD Widget communicates with your page from the iframe using browser postMessage events. Use these events for frontend state such as widget readiness, close actions, cashout submission, identity verification, and linked payout methods. Server-side cashout status updates are delivered separately as signed webhooks. See Server Webhooks.

Listening for Events

Listen for events on the parent window:

window.addEventListener("message", (event) => {
  const { type, payload } = event.data ?? {};
  if (!type?.startsWith("ZBD_")) return;

  switch (type) {
    case "ZBD_WIDGET_READY":
      console.log("Widget loaded", payload?.user);
      break;
    case "ZBD_CASHOUT_SUCCESS":
      console.log("Cashout submitted", payload);
      // Close the widget iframe, refresh balances
      break;
    case "ZBD_WIDGET_CLOSE":
      // User closed the widget — remove the iframe
      break;
  }
});

Event Types

Event	Payload	Description
`ZBD_WIDGET_READY`	`{ user? }`	Widget loaded and authenticated
`ZBD_WIDGET_CLOSE`	—	User closed the widget
`ZBD_CASHOUT_SUCCESS`	`{ cashout_id, amount, currency_code, usd_equivalent }`	Cashout submitted successfully
`ZBD_KYC_COMPLETE`	`{ tier }`	Identity verification approved
`ZBD_METHOD_ADDED`	`{ payout_method_id, type, label }`	Bank account linked via Plaid
`ZBD_AUTH_TOKEN_READY`	`{ auth_token, user? }`	OTP verified, auth JWT available
`ZBD_WIDGET_ERROR`	`{ code, message }`	An error occurred

Overview

Events

API Reference

Testing

Overview

Listening for Events

Event Types

​Overview

​Listening for Events

​Event Types

Overview

Listening for Events

Event Types