Adding step-up verification checks with the DC API

Overview

Presenting a credential via the Digital Credentials API (DC API) is often just one step in a larger verification journey. Relying parties frequently want to run additional checks, for example a liveness or selfie check, step-up authentication, risk scoring, or a document scan, as part of the same session, especially for higher-value transactions.

This page explains a single, platform-generic rule: those additional steps run before or after the DC API presentment, never inside it. It applies to iOS, Android, and React Native holder applications. The reason is easiest to see on iOS, so that is where the constraint is described in the most detail, but the pattern is the same everywhere.

Why extra steps run outside the DC API presentment

On every platform, the DC API presentment is a self-contained, operating-system-mediated exchange. The website asks for a credential, the operating system gathers matching credentials from registered wallets, the holder authenticates and consents, and the wallet returns a presentation. That exchange returns a credential response and nothing more. There is no surface within it for arbitrary UI or additional flows.

How this manifests differs by platform:

• iOS: the presentment is served by Apple's IdentityDocumentProvider app extension. You can customize the extension's UI freely, including positioning elements and adding custom buttons, but it cannot open the camera or run other SDK flows, and closing the extension cancels the request. A custom button can redirect the user to your main application, but doing so closes the extension and ends the session. Any interactive step such as a camera-based check must therefore live in the holder's main application or the requesting website.
• Android: the holder SDK handles the presentment in the background via the Digital Credentials Manager (DCM). The holder application is not foregrounded during the exchange. There is no app extension, so the story is simpler, but the conclusion is identical: there is no in-presentment surface for extra steps.
• React Native: iOS still requires the native IdentityDocumentProvider app extension and Android is handled from JavaScript in the background, so a React Native application inherits both behaviors and the same before-or-after pattern.

Journey flow

The verifier decides where each additional check sits relative to the presentment. A check placed before the presentment can gate whether a credential is even requested. A check placed after the presentment can add assurance once a credential has been accepted, all within the same session.

The step-up check itself, whether a liveness or selfie check, step-up authentication, risk scoring, or a document scan, is one example of a step that runs in this before/after position. Liveness is called out here only because it is the most common request. The same placement applies to any additional check.

Where the step-up check runs

Because the check cannot run inside the presentment, it runs in one of the following places, all of which keep the user within a single verification session:

• On the requesting website (same-device): the website performs the additional check directly, before or after invoking the DC API, using the device's browser and hardware.
• In the holder's main application, via a push notification: after the presentment, the relying party prompts the user to open the holder application and complete the additional check there.
• Via a QR code or deep link (cross-device): the requesting website presents a link that the user follows on a capable device to complete the check, then returns to the original session.

Architecture

A relying party implements this pattern by treating the DC API presentment as one bounded step in an orchestrated flow that it controls end to end.

Orchestrating the session

The relying party's application (website or native app) owns the verification session. It decides which checks are required, in what order, and whether each runs before or after the credential presentment. The DC API presentment is invoked as a single step in that sequence. The relying party resumes control as soon as the credential response is returned.

Running the additional check

The additional check runs on a surface the relying party controls, such as the requesting website, the holder's main application, or a device reached by deep link or QR code, and never inside the DC API presentment. This is where camera-dependent checks such as liveness or document scanning execute, because those surfaces have the necessary hardware access that the presentment surface (an iOS app extension, or an Android background exchange) does not.

Keeping the session continuous

To keep the experience within one session, the relying party links the presentment result and the additional-check result to the same session identifier. On cross-device flows this means transferring the session (for example via a scanned QR code or a deep link) and returning the user to the originating context once the check completes.

What's next?

• Build a holder application that can present a credential via the DC API: iOS, Android, or React Native.
• Learn how the DC API works on the verifier side in the DC API overview and the verifier DC API guide.
• Review the holder-side DC API overview for what the app extension can and cannot do.

Frequently asked questions

Can a liveness check run inside a DC API presentment?

No. On every platform the DC API presentment is a self-contained, operating-system-mediated exchange that returns a credential response. It has no surface for additional user interaction. A liveness check, or any other step-up check, runs before or after the presentment, in the requesting website or the holder's main application, within the same verification session.

Why is this most visible on iOS?

On iOS the presentment is served by Apple's IdentityDocumentProvider app extension. Its UI is fully customizable, but the extension has no camera access and cannot run other SDK flows, and closing it cancels the request, so any interactive step such as a camera-based check must live in the main app or the website. On Android the SDK handles the presentment in the background via the Digital Credentials Manager, so there is likewise no in-presentment surface for extra steps. This is the same conclusion, reached more simply.

Does MATTR provide a liveness check?

No. Liveness, document scanning, risk scoring and similar checks are integrated by the relying party around the DC API presentment. MATTR provides the credential presentment and verification. The additional assurance steps are the relying party's responsibility.

Does this apply to React Native applications?

Yes. On React Native, iOS still requires the native IdentityDocumentProvider app extension and Android is handled from JavaScript in the background, so a React Native application inherits both platform behaviors and the same before-or-after pattern.