Skip to content

Partner Widget Installation Guide

This guide walks partners through registration, activation, configuration, and integration of the Gyzer widget for deposit and withdrawal flows.

1. Overview

The Gyzer partner widget enables your users to:

  • Deposit fiat and receive crypto (USDC, USDT, etc.)
  • Withdraw crypto to fiat
  • Complete KYC verification (SumSub)
  • Manage wallets and bank accounts

Integration Modes

Mode Description Use Case
Standalone Widget with its own registration/login Users sign up directly in the widget; you embed it with your public key
Embed Pre-authenticated widget via onramp token You already onboard users; pass them to Gyzer with optional KYC share token

2. Registration

Partners register via a public API endpoint. No authentication is required.

Endpoint: POST /public/partners/register

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

Request Body

{
  "name": "Acme Finance",
  "slug": "acme-finance",
  "contact_email": "partners@acme.com",
  "contact_name": "Jane Doe",
  "website_url": "https://acme.com",
  "settings": {
    "logo_url": "https://cdn.acme.com/logo.png",
    "allowed_origins": ["https://app.acme.com", "https://acme.com"],
    "widget_css": "--brand-primary: #0ea5e9; --brand-radius: 14px;"
  }
}
Field Required Description
name Yes Partner display name
contact_email Yes Contact email for Gyzer team
slug No URL-friendly identifier (auto-generated from name)
contact_name No Primary contact name
website_url No Partner website
settings No Optional branding and allowed origins

Response

{
  "success": true,
  "partner_id": 42,
  "status": "PENDING",
  "slug": "acme-finance"
}

Registration Flow

flowchart LR
    subgraph Partner [Partner]
        P1[Submit registration]
    end
    subgraph Gyzer [Gyzer API]
        A1[POST /public/partners/register]
        A2[Create partner PENDING]
        A3[Notify admin]
    end
    subgraph Admin [Admin]
        AD1[Review request]
    end
    P1 --> A1
    A1 --> A2
    A2 --> A3
    A3 --> AD1

3. Activation

After registration, your partner status is PENDING. The Gyzer team reviews and approves your application.

Admin Actions

  1. Approve the partner (status becomes APPROVED)
  2. Create API key for the Partner API
  3. Provide credentials to you:
  4. API Key – for X-Partner-Key header (Partner API)
  5. Public Key – for standalone widget embedding

Activation Flow

flowchart LR
    subgraph Admin [Gyzer Admin]
        A1[Review partner]
        A2[Approve partner]
        A3[Create API key]
        A4[Share credentials]
    end
    subgraph Partner [Partner]
        P1[Receive API key]
        P2[Receive public key]
    end
    A1 --> A2
    A2 --> A3
    A3 --> A4
    A4 --> P1
    A4 --> P2

4. Information Needed From Partners

Before Activation

Item Purpose
name Display name
contact_email Primary contact
website_url Partner website
allowed_origins Domains that may embed the widget (required for iframe)

For Branding (Optional)

Item Purpose
logo_url Logo shown in widget header
widget_css CSS variables for colors and radius

For SumSub Token Sharing (If Applicable)

If you already perform KYC with SumSub and want to pass verified users to Gyzer:

  • Obtain Gyzer's SumSub client ID from the Gyzer team
  • Configure Gyzer as an allowed client in your SumSub dashboard

5. CSS Customization

You can customize the widget appearance using CSS variables. Set them via PATCH /partners/settings or during registration in settings.widget_css.

Design System (Default Palette)

The default widget uses an emerald/zinc color scheme:

Token Hex Role
emerald-500 #10b981 Primary brand (buttons, accents, highlights)
emerald-400 #34d399 Text accents, icons, badges
emerald-200 #a7f3d0 Gradient endpoints
emerald-600 #059669 Button hover states
black #000000 Primary background
zinc-950 #09090b Secondary background sections
zinc-900 #18181b Card backgrounds
zinc-400 #a1a1aa Body text
zinc-500 #71717a Muted/secondary text
zinc-300 #d4d4d8 Slightly elevated text
white #ffffff Headings and primary text
white/5-10 5-10% opacity white Subtle borders and overlays

Allowed Variables

Variable Default Description
--brand-primary #10b981 Primary accent (buttons, highlights)
--brand-primary-hover #059669 Button hover states
--brand-accent #34d399 Text accents, icons, badges
--brand-glow #a7f3d0 Gradient endpoints
--brand-bg #000000 Primary background
--brand-surface #18181b Card backgrounds
--brand-surface-alt #09090b Secondary sections (dropdowns, etc.)
--brand-border rgba(255, 255, 255, 0.08) Border color
--brand-text #ffffff Headings and primary text
--brand-text-secondary #d4d4d8 Slightly elevated text
--brand-muted #a1a1aa Body text
--brand-muted-alt #71717a Muted/secondary text
--brand-radius 14px Border radius (14px, 12px, 1rem)

Format

--brand-primary: #0ea5e9;
--brand-bg: #0f172a;
--brand-radius: 14px;
  • Use semicolons between declarations
  • Colors: hex, rgba(), or named colors
  • Radius: px, rem, em, or %

Example

{
  "widget_css": "--brand-primary: #0ea5e9; --brand-bg: #09090b; --brand-surface: #18181b; --brand-radius: 12px;"
}

6. Widget Installation

6a. Standalone Widget

Use when users register and log in directly in the widget.

Widget URL:

https://partners.gyzernetwork.com/public/widget?public_key=<your_public_key>

Embed as iframe:

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

Requirements:

  • Your domain must be in allowed_origins (set via PATCH /partners/settings)
  • Users who register via this widget are attributed to your partner account via X-Partner-Public-Key

6b. Embed Widget (Pre-Authenticated)

Use when you already onboard users and want to pass them to Gyzer with optional KYC verification.

Step 1: Call the Partner API to get a short-lived token:

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: - phone can be omitted during token issuance. - Non-US users can continue without it. - If the verified user is US-based, the widget will collect a US phone number after SumSub KYC and before DTR account creation continues.

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 using widget_url:

<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

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

7. Widget Responses and Session

Embed Session Exchange

When the embed widget loads, it exchanges the token for a session:

Endpoint: POST /public/widget/embed/session

Request:

{
  "token": "<user_token>"
}

Response:

{
  "success": true,
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "dtr_session_id": "...",
  "user": {
    "id": 123,
    "email": "user@example.com",
    "phone": "+1234567890"
  },
  "widget_config": {
    "allowed_flows": ["deposit"],
    "allowed_tokens": ["USDC"],
    "allowed_networks": ["BASE"],
    "requires_kyc": false,
    "requires_otp": false,
    "has_wallet": true,
    "simplified_mode": true
  }
}

The widget uses these tokens internally for subsequent API calls (deposits, withdrawals, etc.). You do not need to handle this exchange yourself when embedding the widget.

8. SumSub Token Sharing Setup

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

Flow

  1. Your user completes KYC in your SumSub flow (must meet minimum requirements for provider approval — US)
  2. You call SumSub's API to generate a share token for that applicant
  3. You pass the share token to POST /partners/user-token
  4. Gyzer validates the token server-side and creates/links the user with the existing KYC status

Partner Setup

  1. Obtain Gyzer's SumSub client ID from the Gyzer team
  2. Configure Gyzer as an allowed client in your SumSub dashboard (for share token generation):
  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 API details, see SumSub Share Token Guide.

SumSub Share Token Flow

sequenceDiagram
    participant User
    participant PartnerApp
    participant PartnerSumSub
    participant SumSubAPI
    participant GyzerAPI

    User->>PartnerApp: Completes KYC
    PartnerApp->>PartnerSumSub: KYC complete
    PartnerSumSub->>SumSubAPI: generate_share_token(applicant_id, gyzer_client_id)
    SumSubAPI-->>PartnerSumSub: share_token
    PartnerSumSub-->>PartnerApp: share_token
    PartnerApp->>GyzerAPI: POST /partners/user-token (sumsub_share_token)
    GyzerAPI->>SumSubAPI: Validate share token
    SumSubAPI-->>GyzerAPI: Applicant data
    GyzerAPI-->>PartnerApp: token, widget_url

Request Example

{
  "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 only becomes mandatory later for verified US users before DTR account creation resumes.

9. Allowed Origins (CORS / frame-ancestors)

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

Default Widget (No Partner)

The default widget at /public/widget (no public_key) uses the WIDGET_DEFAULT_ALLOWED_ORIGINS environment variable. Set a comma-separated list of origins:

WIDGET_DEFAULT_ALLOWED_ORIGINS=https://gyzernetwork.com,https://*.gyzernetwork.com,https://gyzernetwork-enterprise-solutions-d4f3a2f8.base44.app

Partner Widget Allowed Origins

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