---
title: "Digital ID: Bank Redirect"
url: "https://developer.incode.com/sdk-reference/digital-id-redirect/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# Digital ID: Bank Redirect
:::info
  This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference).  Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade. <br /><br />Full rollout to all clients still TBD.
:::

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:

| Provider | Scheme | Country | Portrait returned |
| -------- | ------ | ------- | ----------------- |
| `trinsic_netherlands_idin` | iDIN (bank identification, PSD2-aligned) | Netherlands | No |
| `trinsic_finnish_trust_network` | FTN (bank IDs + Mobile ID, eIDAS) | Finland | No |

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](/sdk-reference/web-sdk-2-module-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](#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:

| Option | Type | Required | Description |
| ------ | ---- | -------- | ----------- |
| `digitalIdReturnUrl` | `string` | ❌ | HTTPS page the bank returns the user to. Defaults to the current page (origin + pathname). Override it when your return route differs. Query parameters you add are preserved. |
| `digitalIdReturn` | `{ returnParams: RedirectReturnParams }` | ❌ | Pass on the **return leg only**. Hands the bank's return parameters to the SDK so it resumes the verification instead of starting the step fresh. |

```typescript
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:

```typescript
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):

```typescript
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`:

| `failureReason` | Meaning |
| --------------- | ------- |
| `USER_CANCELED` / `RP_CANCELED` | The user backed out at the bank. Neutral copy — not an error. |
| `AUTHENTICATION_FAILED` | Bank authentication failed. Retry offered. |
| `VERIFICATION_FAILED` | The scheme could not verify the identity. |
| `SESSION_EXPIRED` / `SESSION_TOKEN_EXPIRED` | The verification session lapsed before completion. |
| `PROVIDER_INTERNAL_ERROR` / `RESULTS_EXCHANGE_FAILED` / `INVALID_REDIRECT_RESULT` | Technical error on the provider side. |

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:

| Call | Purpose |
| ---- | ------- |
| `POST /omni/v2/digital-id/verifications` | Create a verification. Returns `verificationId` and `flowData.launchUrl` (billable moment). |
| `POST /omni/v2/digital-id/verifications/{id}/response` | Submit the bank's return parameters. |
| `GET /omni/v2/digital-id/verifications/{id}/status` | Poll verification status — fallback when results are delayed. |
| `POST /omni/v2/digital-id/verifications/{id}/refresh` | Refresh an expiring `launchUrl` without creating a new (billable) verification. |

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

## See also

- [ID Capture](/sdk-reference/web-sdk-2-module-id-capture/): the module that hosts this sub-flow
- [Session Management](/sdk-reference/web-sdk-2-session-api/): session identifiers and re-attachment
- [IncodeFlow Component](/sdk-reference/web-sdk-2-incodeflow-component/): `FlowConfig` reference