Reference

Sessions API

The requests your server sends and the answers it receives.

Start with the test environment

These guides use the staging API and an issued TEST merchant secret key. Public self-service access is not enabled. You can try the complete flow without a key at Fake Night Club.

Example

API origin: https://api-staging.wristband.id
Authorization: Bearer <your_test_secret_key>

Keep the secret key on your server. The browser receives a session ID, never the key. Test checks, including checks with a real wallet, are not live age verification.

Choose your integration

Hosted page: send the visitor to our verification page and read the result when they return.
Embedded Next.js: show the QR code inside your site and open the wallet from the phone.

Create a session

Request · POST /v1/sessions

POST /v1/sessions
Authorization: Bearer <your_test_secret_key>
Content-Type: application/json

{
  "scopes": ["age_over_18"],
  "reference": "Fake_ticket_47",
  "redirect_uri": "https://your-site.example/verify/return",
  "locale": "en-GB"
}

Register your exact HTTPS return URL before using it. Replace the example domain with your own. No prefixes or wildcards. Use a unique opaque reference for each attempt. Never send names, email addresses or dates of birth.

A successful request returns HTTP 201 with session_id, url, expires_at, providers and your reference. Store the attempt against the visitor’s checkout session before showing the wallet UI.

The optional providers array restricts this check to enabled wallet IDs. Omit it to allow all available wallets for the merchant, scopes and environment. An empty list is invalid. The region in locale changes ordering, not eligibility.

Check Wallet availability before choosing a national wallet. A prepared country module is not automatically enabled for a merchant or for live verification.

Read the result

Request and response · GET /v1/sessions/{id}

GET /v1/sessions/<session_id>
Authorization: Bearer <your_test_secret_key>

// Completed response, selected fields:
{
  "session_id": "<session_id>",
  "reference": "Fake_ticket_47",
  "status": "completed",
  "scopes": ["age_over_18"],
  "result": true,
  "claims": { "age_over_18": true },
  "env": "test",
  "receipt": "<signed JWS>"
}

Read on your server using the session ID you saved, not one supplied by a browser callback. Match the session, reference, scopes and environment to the attempt.

Status	Meaning
`pending` / `awaiting_wallet`	No answer yet. Read again with a delay.
`completed`	Read the boolean result. Both true and false are completed answers.
`failed` / `expired`	No completed answer. Offer a new attempt. Do not grant access.

Sessions normally allow five minutes to start. An already waiting wallet has up to 60 seconds of additional grace. Use the server status rather than turning a client timer into an approval.

Receipts

A completed answer includes an ES256 JWS with type wristband-receipt+jwt. Verify it with a standard JOSE library and keys from /.well-known/jwks.json on the configured API origin. Check issuer, merchant audience, session, reference, scopes and environment. Never fetch keys from an arbitrary URL in a token.

Receipts have no expiry: they record a check, not a permanent right of entry. Your server decides whether a check is fresh enough and which transaction it belongs to. A production decision requires the live environment.

Errors and retries

Handle HTTP errors before reading an outcome. 400 means an invalid request. 401/403 means access was refused. 404 means the session is unavailable. 429 means slow down. On a network error or 5xx, keep the existing attempt. Session creation has no promised idempotency key, so do not automatically repeat a timed-out POST.