Verification Flow

The Verification Lifecycle

A session can have one of the following statuses:

Status	Description
`initiated`	The session has been created, and communication with the eID provider is starting.
`awaiting_user_action`	Waiting for the user to take action (e.g., QR code displayed, awaiting redirect).
`authenticating`	(Optional) The user is actively authenticating in their eID app.
`completed`	The user has successfully completed the verification. Fetch user + provenance via `GET /verifications/{id}/userinfo`.
`failed`	The verification failed (e.g., user rejection, incorrect credentials). Check the `error` field for details.
`expired`	The session expired because the user did not complete the action in time.
`cancelled`	The verification was cancelled by the developer (RP) or the user.

Verification Flows

Every verification starts with POST /verifications and ends with GET /verifications/{id}/userinfo. The flowType in the create response tells you what happens in between. Hopae Connect selects the flow from the eID provider. Pick a flow type. Each tab shows the flow, what you do, and why the create response has that status.

Redirect
QR
Push
Push (Query)
DC

The user signs in on the provider’s own page and comes back to your redirectUri. Key eID providers: most European eIDs, for example mitid.

What you do: send the user to flowDetails.authorizationUrl. When the user is back on your redirectUri, check the status.
Why awaiting_user_action: the provider owns the sign-in page. Hopae has no result until the user signs in there.

The user scans a QR code with the eID app on their phone and approves there. Key eID providers: FrejaID, Diia, KMDL, BankID Sweden.

What you do: render flowDetails.qrData as a QR code (on a phone, open flowDetails.linkData instead), then poll.
Why awaiting_user_action: the credential lives in an app on another device. Hopae learns the result by asking the provider when you poll.

Hopae sends the request to the eID app on the user’s registered device. The user approves there. Key eID providers: Smart-ID, Audkenni, Evrotrust.

What you do: show a waiting screen, then poll.
Why awaiting_user_action: the request is already on the user’s phone. Only the user’s approval can finish it.

These eIDs (for example ng-nin, ng-bvn, br-cpf) are listed as push, but nothing is sent to the user. Hopae checks the ID number or image you send with the source (the national registry) during the create call, so the create response already carries the final status.

What you do: nothing between create and userinfo. No waiting screen, no polling. On failed, read error.code in the create response (for example INVALID_ID_NUMBER).
Why completed / failed right away: the check needs only data you already sent, so there is nothing to wait for. Hopae answers when the source answers.
The create call takes as long as the source, usually a few seconds. Allow at least 30 seconds before your HTTP client times out.
Create answers 201 either way. A later GET /verifications/{id} returns the stored result without asking the source again.

Lookup eIDs (21 provider IDs)

Provider ID	eID
`ng-nin`	Nigeria NIN
`ng-bvn`	Nigeria BVN
`ng-vid`	Nigeria Voter ID
`za-nid`	South Africa National ID
`ug-nin`	Uganda National ID
`kenya-nid`	Kenya National ID
`kenya-pass`	Kenya Passport
`kenya-alien`	Kenya Alien Card
`angola-nin`	Angola National ID
`ghana-card`	Ghana Card
`ci-nid`	Côte d’Ivoire National ID
`br-cpf`	Brazil CPF
`br-cnh-match`	Brazil CNH + biometrics
`mx-curp`	Mexico CURP
`mx-ine-qr`	Mexico INE QR Code
`chile-run`	Chile RUN
`peru-dni`	Peru DNI
`in-pan-match`	India PAN
`id-nik-match`	Indonesia NIK
`id-nik-biometric-match`	Indonesia NIK + biometrics
`ph-nid`	Philippine National ID

Your web page asks the user’s digital wallet for a credential through the W3C Digital Credentials API. Key eID providers: US Mobile Driver License (us-mdl), US Digital Passport (us-id-pass).

What you do: mint the wallet request, invoke the wallet in the browser, and submit its response. There is no status polling.
Why awaiting_user_action: only the user can release the credential from their wallet.

For detailed instructions on each flow, see the Integration Guides section.

Getting Started

Integrations

Concepts

Verifications

Data Types

Security

Verification Flow

The Verification Lifecycle