workflow_id.
Your backend starts the verification and retrieves its result; your interface guides the person through the wallet’s required authentication.
An API integration still requires the person to authenticate and approve sharing their identity.
You cannot verify someone by submitting their personal identifier without that interaction.
How verification works
- Your backend checks the wallet catalog, then calls an available wallet’s start endpoint using your application API key.
- Didit returns a verification reference and the action the person needs to take.
- Your application opens the authentication page or displays the wallet’s approval instructions.
- The person authenticates with their wallet.
- Your backend retrieves the verified result and handles completion notifications.
Backend integration
Use List digital ID wallets to obtain the current endpoints, required fields and availability for your application. Keep yourx-api-key on your backend.
Do not place it in a browser bundle or mobile application.
Use a distinct Idempotency-Key for each new verification attempt and reuse that key when retrying the same start request.
Changing the request while reusing its key is a conflict, not a new verification attempt.
Each wallet has its own start URL, such as /v3/id-verification/wallets/ftn/ for Finnish Trust Network.
The request_id identifies the standalone verification for subsequent operations.
Use vendor_data for your own reference, up to 2,000 UTF-8 bytes, and metadata for an optional JSON object.
Both are returned with the result and completion webhook.
These operations use the API key of the application that started the verification.
Polling and authentication availability depend on the selected wallet.
A cancel declines a pending verification without charging for it, and returns a completed one unchanged.
For Smart-ID and Mobile-ID, a cancel that arrives while a poll is checking the approval waits a few seconds for that poll.
It then declines the verification, or returns it as
verified if the person had already approved.
A verification the person is completing at that moment cannot be cancelled: the response is 409 with error: "verification_in_progress" and a Retry-After header.
Retry after that many seconds to read the completed result.
Register your return destination
Redirect wallets send the person back to your application after authentication. Register the exact hostname before starting a verification:return_url, such as https://app.example.com/identity/complete, in the start request.
Use bare hostnames in allowed_return_hosts, without a scheme, path or wildcard.
Register each subdomain you use separately, up to 20 hostnames.
Updating allowed_return_hosts replaces the registered list, so include every hostname you want to keep.
GET /v3/webhook/ returns the current list; see Webhook configuration.
You do not need a workflow or a white-label domain to register a return destination.
The destination is a browser return page; configure completion webhooks separately for your backend.
Example: Finnish Trust Network
After registering your return hostname, start a Finnish Trust Network verification:request_id and send the person’s browser to wallet_verification.next_action.url when its type is redirect.
After the person returns, retrieve the result from your backend:
wallet_verification.outcome:
Only use the identity when the outcome is
verified and simulated is false for a real identity check.
A pending response can carry a next action; terminal responses have no next action.
Authentication experiences
Redirect wallets return an authentication URL. Open that URL in the person’s browser, let them complete the wallet’s authentication process and return them to your registered destination. Read the result from your backend instead of trusting a return URL parameter as proof of identity. Smart-ID and Mobile-ID use an approval prompt on the person’s phone. Your interface collects the required personal identifier; Mobile-ID also needs the associated phone number. Display the comparison code and instruct the person to approve only when it matches the code on their phone. Their PIN belongs in the wallet or phone prompt, never in your form or an API request. Poll from your backend at the returnedpoll_interval_seconds for prompt feedback.
Didit also checks pending phone approvals in the background, so completion can reach your webhook after the person closes your page.
Google Wallet is asked from your own page or app through the Digital Credentials API, with no redirect; see Digital Credentials wallets (Google Wallet).
The available interaction depends on the selected wallet.
Do not assume every wallet supports an embedded form, a QR code or authentication without a browser.
Digital Credentials wallets (Google Wallet)
Google Wallet is asked directly by your web page or Android app, using the W3C Digital Credentials API. There is no redirect, no Didit-hosted page and no Didit QR code. It is available in production and in sandbox. Sandbox applications need no registration; each production application registers once from the console (ID verification step, Google Wallet row, Register with Google) before it can use Google Wallet. Check List digital ID wallets for what your application can start now.1
Start with your origin
Your backend calls
POST /v3/id-verification/wallets/google-wallet/ with the person’s country (USA, GBR, BRA, SGP or TWN) and the origin that will ask the wallet.
The origin is the HTTPS origin of your page, such as https://app.example.com, whose host must be one of your registered return hostnames or your white-label domain.
For an Android app it is android:apk-key-hash: followed by the base64 SHA-256 of your app’s signing certificate, without padding.
The wallet refuses a request made from any other origin.
There is no return_url.2
Ask the wallet inside a user gesture
The response has
wallet_verification.interaction = "digital_credentials" and next_action.type = "request_digital_credential".
Pass next_action.digital_credentials.request to the browser or to Android Credential Manager, from a tap or click on the origin you started with.
On desktop the browser shows its own QR code when the wallet is on another device.3
Submit what the wallet returned
Send the returned
{protocol, data} to your backend and from there to POST /v3/id-verification/wallets/verifications/{request_id}/response/ as {"response": {...}}.
The request can be submitted once; a second submit returns the already decided verification.4
Read the outcome
The submit response is the decided verification.
You can also read it with
GET /v3/id-verification/wallets/verifications/{request_id}/ or receive it in the completion webhook."DigitalCredential" in window is true.
navigator.credentials.get must run in a user gesture, so call it from the click handler rather than after an asynchronous step.
On Android, use Jetpack Credential Manager (androidx.credentials 1.5.0 or later) with the same request:
A credential that fails verification is a decided verification with a
failed outcome, not an error response.
Only the fields that the verification requests leave the wallet, and the result contains the identity attributes that the wallet returned.
A Google Wallet ID pass or US state mobile driving licence does not return a portrait.
In a sandbox application the flow is simulated with the same steps and returns simulated: true.
Any submitted response decides the verification according to the sandbox_scenario, so you can build the full browser or app journey without a real credential.
Completion webhooks
Configure an application webhook destination forstatus.updated using the webhook integration guide.
Use webhook_version: "v3" for the decision structure described here.
Verify the webhook signature on your backend before processing it.
The webhook’s session_id matches the request_id returned by the wallet API.
A completed wallet identity appears in the webhook’s decision.id_verifications array with verification_method: "wallet".
You can also use the identifier to retrieve the dedicated wallet API result.
Handle approval and decline notifications, including cancelled and expired verifications.
Make your webhook handler idempotent because failed deliveries are retried.
A browser return is not a completion webhook and its query parameters are not proof of identity.
Returned identity
Use the normalized identity fields for names and dates of birth when those fields are returned. Wallet-specific attributes describe the identity information shared by the selected wallet. The available attributes vary by wallet and country. An authenticated identity does not imply that a portrait, address or every other requested attribute is available.Test in sandbox
An application in Didit sandbox mode simulates wallet verification without contacting a wallet provider or charging credits. The response identifies these requests withwallet_verification.simulated: true.
A simulated approval is sample data, not a verified real-world identity.
For a redirect wallet, follow the returned URL to exercise the callback and return to your application.
For Smart-ID or Mobile-ID, use the polling endpoint to complete the simulated approval; no notification is sent to a phone.
To test failure handling, set sandbox_scenario to wallet_cancelled, wallet_timeout or wallet_provider_error when starting a request.
Live applications reject sandbox_scenario.
Didit sandbox simulation is separate from testing against a provider’s own test environment.
Successful simulation does not establish live provider access or production availability.
ConnectID provider sandbox
ConnectID’s provider sandbox uses test banks and is separate from Didit sandbox simulation. When provider sandbox access is configured for your integration, pass the selected bank’sauthorisation_server_id to the ConnectID start endpoint.
Use the ID returned by the ConnectID bank selector; do not send a bank URL or an arbitrary issuer.
Omitting the field selects the default test bank.
The field is specific to ConnectID and does not change the requested identity attributes.
The initial bundle requests given name, family name and date of birth.
Follow the returned next_action to authenticate, then retrieve or poll the verification result.
Only a completed result with an approved status confirms that verification succeeded; returning to your application does not.
ConnectID remains Coming soon in production while onboarding and certification are completed.