Copy page

Get Started

Digital ID Overview

Privy Digital ID is an identity verification widget. A merchant embeds the widget in a web iframe or a native WebView. Privy operates the camera, biometric checks, and identity flow inside the widget.

The merchant completes three integration tasks:

1. Create a session from the merchant backend with an API key.
2. Load the returned session_url in an iframe or WebView.
3. Receive the result through a server callback or a postMessage event.

The authoritative result is the Privy-signed JWT after the merchant backend verifies it. The exchange endpoint and the server callback are two delivery channels for that result. Use front-channel events only to update the user interface.

Before you start

Get these items from the Privy team for each environment:

• Your data package, Contact or Identity, and its data items. See Data Packages.
• An API key. See Authentication.
• Registration of your web origin in the Privy allowlist.
• The configuration of your server callback URL. See Server Callback.
• Your widget settings: the consent confirmation window, the default OTP channel, and your terms-of-use and privacy-policy URLs.

How verification works

Privy operates each step inside the widget. The steps are the same for both data packages.

Step	Privy operation
1. Input	The user enters one identifier: PrivyID, email, NIK, or mobile number. Indonesian and international mobile numbers are supported.
2. Liveness	Privy uses the camera to confirm that a live person is present.
3. Face match	Privy compares the live selfie with the selfie recorded for that identity. The user has up to three attempts.
4. OTP	Privy sends a one-time password. WhatsApp is the default channel. The merchant can change the default, and the user can select another channel.
5. Consent	The user reviews the shared data. The user continues or rejects the request within the confirmation window.
6. Result	Privy sends the verified result by callback and exchange code.

The merchant does not call the internal widget endpoints for identity input, liveness, face matching, OTP, or consent. The user journey shows the screen for each step.

Integration sequence

Solid arrows are requests. Dashed arrows are responses and events.

Privy delivers the verified-data JWT through two channels: the exchange response and the server callback. The same result can arrive through both channels. Make result processing idempotent with session_id.

Integration model

Digital ID uses a custom session and postMessage integration. It does not use a complete OIDC flow. Privy controls the order of the steps on its servers, so users cannot skip a step. A user can safely reload the widget.

Continue with the quickstart, or review the data packages.

Version 1.0

The July 2026 release (API version 1.0.0) includes:

• The create-session, embed, success-event, and exchange-code flow.
• Consent after the face match and OTP.
• Verified-data delivery by JWT through exchange and callback.
• An optional shared-data preview in the privy:success event.
• WebView camera and permission contracts for iOS and Android.
• The Contact and Identity data packages.
• OTP for both data packages.
• RSA-encrypted identity data in the Identity package.

The changelog lists later changes that affect merchant integrations.