Skip to content

Embed Widget Guide

This guide covers only the Embed Widget (pre-authenticated) integration. Use it when you already onboard users and want to pass them to Gyzer with optional KYC verification.

Quick start: Use the Setup Checklist for a step-by-step action list.

For registration, activation, and the full installation guide, see Widget Installation Guide.

Base URLs:

  • Production https://partners.gyzernetwork.com/
  • Staging/Sandbox https://partners-staging.gyzernetwork.com/ (for testing)

1. How It Works

  1. Your backend calls POST /partners/user-token with the user's external_user_id, email, and optionally phone.
  2. You receive a short-lived token and widget_url (embed URL).
  3. You render an iframe with that URL on your page.
  4. The widget loads, exchanges the token for a session, and shows the deposit/withdraw UI.

2. Integration Steps

Step 1: Get a Short-Lived Token

Call the Partner API to get a token for the user:

curl -X POST "https://partners.gyzernetwork.com/partners/user-token" \
  -H "X-Partner-Key: $PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_12345",
    "email": "user@example.com",
    "phone": "+1234567890",
    "sumsub_share_token": "optional-if-you-have-kyc",
    "wallet_address": "0x...",
    "wallet_chain": "ERC20"
  }'

Required fields: external_user_id, email

Optional fields: phone, sumsub_share_token, wallet_address, wallet_chain

Phone behavior: - Pass phone if you already have it. - If you omit phone, the user can still register and continue through KYC. - For US users, Gyzer collects a US phone number after SumSub KYC is verified and before DTR account creation resumes.

Optional: If you use SumSub for KYC, include sumsub_share_token to skip re-verification. See SumSub Share Token Guide for how to obtain it.

Recommended: If the user has already connected their wallet in your app, pass wallet_address and wallet_chain to avoid the user having to add or connect their wallet again in the widget.

Response:

{
  "success": true,
  "token": "abc123...",
  "expires_at": "2025-02-19T15:30:00Z",
  "expires_in": 600,
  "widget_url": "https://partners.gyzernetwork.com/public/widget/embed?t=abc123..."
}

Step 2: Embed the Widget

Use widget_url in an iframe:

<iframe
  src="https://partners.gyzernetwork.com/public/widget/embed?t=<token>"
  width="450"
  height="700"
  frameborder="0"
  allow="clipboard-write"
></iframe>

Important:

  • Token is single-use and expires in ~10 minutes
  • Generate a new token for each user session
  • Your domain must be in allowed_origins

3. Embed Flow Diagram

sequenceDiagram
    participant User
    participant PartnerApp
    participant PartnerBackend
    participant GyzerAPI
    participant Widget

    User->>PartnerApp: Opens deposit flow
    PartnerApp->>PartnerBackend: Request widget for user
    PartnerBackend->>GyzerAPI: POST /partners/user-token
    GyzerAPI-->>PartnerBackend: token, widget_url
    PartnerBackend-->>PartnerApp: Embed URL with token
    PartnerApp->>Widget: Load iframe (embed?t=token)
    Widget->>GyzerAPI: POST /public/widget/embed/session
    GyzerAPI-->>Widget: access_token, user, widget_config
    Widget->>User: Show deposit/withdraw UI

4. SumSub Token Sharing (Optional)

If you perform KYC with SumSub and want to pass verified users to Gyzer without re-verification:

Minimum KYC flow: Your SumSub flow must meet the minimum requirements for provider approval (US).

Partner Setup

  1. Obtain Gyzer's SumSub client ID from the Gyzer team
  2. Configure Gyzer as an allowed client in your SumSub dashboard:
  3. Go to Reusable identity → Partners → Recipients
  4. Add Gyzer's client token as a recipient so you can generate share tokens for Gyzer's client ID

SumSub add recipient

Add Gyzer as a recipient in SumSub: Reusable identity → Partners → Recipients

  1. When generating the share token, use for_client_id = Gyzer's client ID

For detailed steps on calling SumSub's API, see SumSub Share Token Guide.

Request with Share Token

Obtain the share token from SumSub's API (see SumSub Share Token Guide), then include it in your POST /partners/user-token request:

{
  "external_user_id": "user_12345",
  "email": "user@example.com",
  "phone": "+1234567890",
  "sumsub_share_token": "<token_from_sumsub_api>",
  "wallet_address": "0x...",
  "wallet_chain": "ERC20"
}

Note: external_user_id and email are required for all requests. phone is optional and is only collected later for verified US users if it was not supplied earlier.

5. Allowed Origins

The widget uses the frame-ancestors Content Security Policy directive. Only domains listed in allowed_origins can embed the widget in an iframe.

Via API (PATCH /partners/settings):

{
  "allowed_origins": [
    "https://app.yourdomain.com",
    "https://yourdomain.com"
  ]
}

Rules:

  • Must start with http:// or https://
  • No whitespace
  • Invalid values return 400