Server-Verify mode

The server-verify mode allows you to unlock the UI only after partner backend confirmation.

When to use it

Use this mode if your application must:

• create a server session before marking the user as verified
• execute business checks after grant_code (fraud, rights, etc.)
• avoid frontend unlocking based solely on browser feedback

Activation

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
        data-success-path="/verified"
        data-server-verify="true"
        data-server-verify-endpoint="/api/zykay/server-verify"
        data-server-verify-timeout="30"></script>

Exact loader contract v4

When grant_code is detected in the URL:

1. The loader emits zykay:grant-received with { grantCode }
2. The loader does not emit zykay:verified in server-verify mode
3. The loader polls data-server-verify-endpoint in GET every 1s (credentials: 'include')
4. The loader waits for a JSON response with {"verified": true}
5. If received, the loader emits zykay:verified-server and passes success
6. If timeout reached (default 30s), error SERVER_VERIFY_TIMEOUT

Contract from your partner endpoint

Endpoint: GET /api/zykay/server-verify

• 200 {"verified": false}: backend processing still in progress
• 200 {"verified": true}: verification confirmed, the loader unlocks

Minimal example:

import { NextResponse } from 'next/server'
 
export async function GET() {
  const verified = false // Read your application session state
 
  return NextResponse.json(
    { verified },
    {
      headers: {
        'Cache-Control': 'no-store',
      },
    }
  )
}

Recommended flow (frontend + backend)

window.addEventListener('zykay:grant-received', async (event) => {
  const grantCode = event.detail?.grantCode
  if (!grantCode) return
 
  // 1) Exchange grant_code on backend
  await fetch('/api/zykay/exchange', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ grant_code: grantCode }),
    credentials: 'include',
  })
 
  // 2) Backend marks session as "verified"
  // 3) /api/zykay/server-verify returns {"verified": true}
})

Manual mode (without endpoint)

If you don't use data-server-verify-endpoint, you can confirm manually:

window.__ZYKAY_WIDGET_V4__?.confirmServerVerified()

This mode is useful if your app itself controls the confirmation cycle.