Frontend Integration

Integrate ZYKAY with loader v4 (QR desktop + deep link mobile).

Facility

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_xxx"
        data-success-path="/verified"></script>

Two attributes are required: data-partner-id and data-success-path.

What the loader does

Creates a verification request (POST /api/w/verify-request)
Displays QR code on desktop
Open the ZYKAY app on mobile (deep link)
Poll status (GET /api/w/verify-status/:requestId?pt=...)
Redirect to data-success-path with #grant_code=...

Available attributes

Attribute	Required	Default	Description
`data-partner-id`	Yes	-	Your Partner ID (`pk_live_xxx`)
`data-success-path`	Yes	-	Return URL after success
`data-scopes`	No	`isAdult`	Comma separated scopes
`data-locale`	No	`fr`	`fr` or `en`
`data-theme`	No	`dark`	`dark` or `light`
`data-container`	No	`zykay-widget`	ID of an existing container
`data-debug`	No	`false`	Console logs
`data-client-proof-mode`	No	`false`	Enables EUDI Wallet verification
`data-server-verify`	No	`false`	Enables server confirmation mode
`data-server-verify-endpoint`	No	-	Endpoint `GET` partner returning `{"verified": true/false}`
`data-server-verify-timeout`	No	`30`	Timeout (seconds)

Reading `grant_code`

The loader uses the fragment URL (#grant_code=...) to avoid the Referer leak.

<script>
(function () {
  const hash = new URLSearchParams(window.location.hash.slice(1));
  const grantCode = hash.get('grant_code');
  if (!grantCode) return;
 
  fetch('/api/zykay/exchange', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ grant_code: grantCode })
  }).then(() => {
    // Nettoie le hash après traitement
    history.replaceState({}, '', window.location.pathname + window.location.search);
  });
})();
</script>

EUDI Wallet mode

Add data-client-proof-mode="true" to enable verification via EUDI Wallet:

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_xxx"
        data-success-path="/verified"
        data-scopes="isAdult,isFrench,isUnique"
        data-client-proof-mode="true"></script>

⚠️

The isMale, isFemale, revealNationality and revealBirthYear scopes are not available with the EUDI Wallet. See the EUDI Wallet documentation for details.

Server-Verify mode (optional)

server-verify mode waits for backend confirmation before UI success.

<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>

Complete contract (events, polling, timeout, expected endpoint): → Mode Server-Verify

Complete example

<div id="zykay-slot"></div>
 
<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
        data-success-path="/verified"
        data-scopes="isAdult,isFrench"
        data-container="zykay-slot"
        data-locale="fr"></script>

Next step

Implement the grant_code backend exchange:

→ Backend (Exchange API)

Quick Start