Digital ID: Bank Redirect

The Digital ID bank redirect lets a user verify their identity with their bank instead of capturing a document. The SDK sends the user to the bank's own site in a full-page redirect; after the user authenticates, the bank returns them to your page and the flow resumes and completes. Verified identity data arrives as OCR-aligned interview data — no document capture, and no selfie-to-ID face match when the scheme returns no portrait.

Supported schemes:

Because neither scheme returns a portrait, the flow skips the ID-to-selfie face match automatically for these verifications.

This is not a standalone step. It runs inside the ID Capture module: when a digital-ID method is enabled, the document chooser offers Digital ID alongside Identity Card and Passport.

Prerequisites

• Web SDK 2.0 enabled for the flow. On a flow running the 1.x experience, the digital-ID configuration is ignored and the chooser never shows the option.
• A digital-ID method on the flow's ID Capture module. Enable iDIN or FTN for the flow in the dashboard. The flow configuration then carries it under digitalIds.methods.
• A registered return URL. The bank returns the user to your page's origin + path. Incode registers this per environment with the identity network — contact your Incode Representative with the exact URL (or origin wildcard) your integration uses. An unregistered return URL makes verification creation fail with HTTP 400.
• A session that survives the redirect. The round trip fully unloads your page. Launch the flow with a resumable session identifier (hosted onboarding links include one), or preserve one yourself — see Surviving the redirect.

How the journey works

1. The user picks Digital ID in the ID Capture chooser (or the flow auto-starts it when it is the only method).
2. The SDK creates a verification and receives a bank launchUrl.
3. The SDK performs a full-page redirect to launchUrl. No popup, iframe, or webview is involved.
4. The user authenticates with their bank.
5. The bank redirects back to your return URL with success, sessionId, and resultsAccessKey appended as query parameters.
6. Your page re-mounts the flow and hands those parameters to the SDK, which resumes the step, submits the result, and shows a success screen. The user taps Continue and the flow proceeds.
7. On failure the user sees reason-specific copy with Try again and Use another method (falls back to the document chooser when the flow allows it).

Configuration

Two FlowConfig fields on <incode-flow> drive the redirect round trip:

type RedirectReturnParams = {
  success: boolean;
  sessionId: string;
  resultsAccessKey: string;
};

Return-leg wiring

Add your own marker to digitalIdReturnUrl so the return leg is detected unambiguously. A canceled verification can return without sessionId or resultsAccessKey, so detecting on those parameters misses cancellations:

const config = {
  clientId: 'YOUR_CLIENT_ID',
  configurationId: 'YOUR_FLOW_ID',
  // ...your existing options
  digitalIdReturnUrl: `${window.location.origin}${window.location.pathname}?digital_id_return=1`,
};

On the returning page load, detect the marker, hand the bank's parameters to the flow config, and remove them from the address bar (resultsAccessKey grants access to the result — do not let it linger in the URL or browser history):

const params = new URLSearchParams(window.location.search);
const isDigitalIdReturn = params.get('digital_id_return') === '1';

if (isDigitalIdReturn) {
  config.digitalIdReturn = {
    returnParams: {
      success: params.get('success') === 'true',
      sessionId: params.get('sessionId') ?? '',
      resultsAccessKey: params.get('resultsAccessKey') ?? '',
    },
  };
  for (const p of ['digital_id_return', 'success', 'sessionId', 'resultsAccessKey']) {
    params.delete(p);
  }
  window.history.replaceState({}, '', `${window.location.pathname}?${params}`);
}

The bank may append additional parameters — read these three and ignore the rest.

Surviving the redirect

The redirect unloads your page, so the returning page must re-attach to the same onboarding session. A fresh session does not know the verification and the resume fails.

• Hosted onboarding links (launched with a session identifier in the URL) resume automatically.
• Self-hosted integrations: persist a resumable session identifier before the flow mounts — for example in sessionStorage, which survives a same-tab redirect round trip — and pass it back into FlowConfig on the return leg.

The verification identifier itself is persisted by the SDK in browser storage and recovered on return; you only preserve the session.

Failure handling

When the verification fails, the ID Capture state is status: 'digitalIdRedirect', phase: 'failed', with a failureReason:

Drive recovery with the ID Capture manager: digitalIdRedirectRetry() starts a new verification, digitalIdRedirectUseAnotherMethod() returns to the document chooser, and digitalIdRedirectContinue() acknowledges the success screen.

Each verification — including every retry — creates a new provider session, which is a billable event. Retries only happen on an explicit user action, never automatically.

API endpoints

The module rides on the Digital ID Verification API. Direct API integrators use the same contract:

Verification status values: CREATED, IN_PROGRESS, COMPLETED, CANCELLED, FAILED, EXPIRED.

See also

• ID Capture: the module that hosts this sub-flow
• Session Management: session identifiers and re-attachment
• IncodeFlow Component: FlowConfig reference