# 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](/digital-id/concepts/data-packages).
- An API key. See [Authentication](/digital-id/concepts/authentication).
- Registration of your web origin in the Privy allowlist.
- The configuration of your server callback URL. See
  [Server Callback](/digital-id/guides/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](/digital-id/concepts/user-journey) shows the screen for each
step.

## Integration sequence

<Mermaid
sequenceDiagram
    chart={`sequenceDiagram
    participant Backend as Merchant backend
    participant Host as Merchant host
    participant Widget as Privy widget
    participant API as Privy API

    Backend->>API: POST /v1/sessions
    API-->>Backend: session_url
    Backend-->>Host: session_url
    Host->>Widget: Load iframe or WebView
    Widget->>API: Input, liveness, face match, OTP, consent
    Widget-->>Host: privy:success with exchange_code
    Host-->>Backend: exchange_code
    Backend->>API: POST /v1/sessions/exchange
    API-->>Backend: Verified-data JWT
    API-->>Backend: Callback with JWT`}
/>

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](/digital-id/get-started/quickstart), or review
the [data packages](/digital-id/concepts/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](/digital-id/changelog) lists later changes that affect
merchant integrations.