Troubleshooting

Common issues with v4 integration and quick fixes.

1) The widget does not appear

Check the two required attributes of the script:

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

Common causes:

data-success-path absent
data-partner-id invalid
CSP blocking of widget-app.zykay.com

2) Error `Missing required data attributes`

The loader logs this error if data-partner-id or data-success-path is missing.

[ZYKAY v4] Missing required data attributes: data-partner-id, data-success-path

3) Verification passed but grant not processed

The grant_code comes in the URL fragment, not in the query string.

const hash = new URLSearchParams(window.location.hash.slice(1));
const grantCode = hash.get('grant_code');

⚠️

The fragment (#...) is not visible on the server side. You need to extract it on the frontend side and then send it to your backend.

4) `INVALID_SIGNATURE` on `/v1/exchange`

Checklist:

Secret decoded in base64 before HMAC
timestamp in seconds (not milliseconds)
Exact canonical string: bodyHash.timestamp.partnerId.nonce
Exact compact JSON body signed and sent

5) Mobile: the app does not open

Check that you are using the official v4 loader
Check that the phone has the ZYKAY app installed
Test without content blockers
Open the Safari/Chrome remote console to confirm the click handler

6) Polling blocked in `pending`

Check:

connectivity to GET /api/w/verify-status/:requestId?pt=...
session expired (TTL exceeded)
consistency between request_id and poll_token

7) EUDI Wallet: the widget does not go into EUDI mode

Verify that the attribute is exactly data-client-proof-mode="true" (not "1", "yes", or true without quotes):

<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"
        data-client-proof-mode="true"
        data-debug="true"></script>

Activate data-debug="true" and check in the console that the mode is detected.

8) EUDI Wallet: the app does not open on iPhone

Check that the ZYKAY app is installed on the phone
Universal Links do not work in in-app browsers (Instagram, Facebook, TikTok) — test in Safari or native Chrome
Check that the QR code points to https://app.zykay.com/verify?request_id=...

⚠️

If your users arrive from social apps (Instagram, TikTok), iOS Universal Links will not work. Suggest opening in Safari.

9) EUDI Wallet: unsupported scope error

The scopes isMale, isFemale, revealNationality and revealBirthYear are not available with the EUDI Wallet. Remove them from data-scopes when data-client-proof-mode="true" is active.

10) EUDI Wallet: long verification time

Scenario	Expected duration
First visit	~15 seconds
Later visit (cache)	~15-30 seconds
Instant connection	~1.7 seconds

If the first visit consistently exceeds 30 seconds, check the phone's network connectivity. For journey details, see Wallet Journey.

11) Debug recommended

Enable:

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

Quick Start