# Integration requirements

This page is a checklist of requirements for integrating BankID with biometrics. It covers flow, permission type and design rules you must follow. You are responsible for ensuring your integration complies.

> **Warning**
>
> Not following these requirements may constitute a breach of your BankID agreement.

If you have not selected a flow yet, start with the [flow overview in Getting started](https://docs.stoe.no/bankid-with-biometrics/getting-started.md).

## At a glance

| ID                                                                                                                             | Topic                     | Not accepted ❌                                | Use instead ✅                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [1.1](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#11-ciba-vs-browser-supported-channels)           | Browser-supported channel | CIBA flow                                     | [Authorization Code Flow](https://docs.stoe.no/bankid-with-biometrics/flows/code.md) or [Iframe Flow](https://docs.stoe.no/bankid-with-biometrics/advanced-topics/iframes-support.md)          |
| [1.2](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#12-custom-ui-in-ciba-flows)                      | Custom UI in CIBA flows   | Custom UI mimicking the BankID client         | A redirect or iframe flow, or [contact us](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#12-custom-ui-in-ciba-flows) before building any custom UI                   |
| [1.3.a](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#13a-redirect-callbacks-in-native-ios-apps)     | Native iOS app redirect   | Redirect flow without `app_callback_uri`      | Redirect flow with `app_callback_uri`                                                                                                                                                          |
| [1.3.b](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#13b-native-app-ui-implementation)              | Native app implementation | WebView                                       | Recommendations on [Native applications](https://docs.stoe.no/bankid-with-biometrics/advanced-topics/native-applications.md)                                                                   |
| [2.1](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#21-permission-type-for-signing)                  | Signing                   | `authentication.v1`                           | [VerifiedConfirmation](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#verifiedconfirmation) or another eSigning product                                                       |
| [2.2.a](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#22a-dont-use-signing-for-payments)             | Payments — general        | Signing permissions                           | [Payment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#payment) or [CardPayment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#cardpayment)               |
| [2.2.b](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#22b-card-payments-must-use-cardpayment)        | Card payments             | `payment.v1` for card / 3-D Secure payments   | [CardPayment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#cardpayment)                                                                                                     |
| [2.2.c](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#22c-dont-use-payment-to-add-cards-or-accounts) | Adding cards/accounts     | `payment.v1` with 0 kr                        | [ApproveCard](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#approvecard) or [ApproveAccount](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#approveaccount) |
| [3.1](https://docs.stoe.no/bankid-with-biometrics/integration-requirements.md#31-one-bankid-one-button)                        | Design requirements       | Separate buttons per level of assurance (LoA) | One BankID = one button, following the [BankID design requirements](https://bankid.no/bedrift/designmanual-knapper)                                                                            |

## 1. Flow requirements

### 1.1 CIBA vs. browser-supported channels

❌ Don't use the CIBA flow when the initiating channel supports a browser.

✅ Instead, use the [Authorization Code Flow](https://docs.stoe.no/bankid-with-biometrics/flows/code.md) (top-level redirect) or the [Iframe Flow](https://docs.stoe.no/bankid-with-biometrics/advanced-topics/iframes-support.md).

**Why this matters:** in browser-capable channels, redirect and iframe flows provide built-in fallback handling. With CIBA, you must explicitly handle fallback for code device users. Additionally, a CIBA flow with a browser makes you responsible for integrating the UI in the browser — work you can avoid by choosing the redirect or iframe flows instead.

### 1.2 Custom UI in CIBA flows

Use the [Authorization Code Flow](https://docs.stoe.no/bankid-with-biometrics/flows/code.md) (redirect) or the [Iframe Flow](https://docs.stoe.no/bankid-with-biometrics/advanced-topics/iframes-support.md) instead of building a custom UI.

> **Never mimic the BankID client**
>
> Under no circumstances may you present a mimic or imitation of the BankID client in your own UI. This causes end user uncertainty and harms the BankID brand. There are no exceptions to this rule.

A custom UI may be permitted when the initiating channel has a very reduced browser — for example a game console or smart TV — where a standard BankID client UI cannot reasonably be rendered.

**Even in these cases, the custom UI must not mimic the BankID client. Contact us or your vendor before implementing a custom UI.**

### 1.3 Native applications

#### 1.3.a Redirect callbacks in native iOS apps

❌ Don't start a redirect flow from a browser inside a native iOS app without supplying `app_callback_uri`.

✅ Instead, supply `app_callback_uri` so the user is returned to your app after authentication.

**Why this matters:** without `app_callback_uri`, an iOS platform limitation leaves many users stuck and unable to return to your app after authentication.

#### 1.3.b Native app UI implementation

❌ Don't use a WebView to implement BankID with biometrics in a native app.

✅ Instead, follow the recommendations on the [Native applications](https://docs.stoe.no/bankid-with-biometrics/advanced-topics/native-applications.md) page.

**Why this matters:** WebViews don't directly support WebAuthn, which is the primary authentication mechanism for BankID with biometrics. WebViews are also less secure than the recommended native app browser approach.

## 2. Permission type requirements

### 2.1 Permission type for signing

❌ Don't use authentication for signing.

✅ Instead, use the [VerifiedConfirmation](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#verifiedconfirmation) permission type or another [eSigning product](https://docs.stoe.no/bankid-esign-provider/introduction.md).

**Why this matters:** `VerifiedConfirmation` is designed for confirming text intent, while `authentication.v1` represents login context.

### 2.2 Permission type for payments

#### 2.2.a Don't use signing for payments

❌ Don't use signing for payments.

✅ Instead, use the [Payment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#payment) or [CardPayment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#cardpayment) permission types.

**Why this matters:** with signing, the merchant supplies a static string that is opaque to BankID and may not match the language shown by the BankID client. `Payment` and `CardPayment` instead provide a payment-specific UX and give BankID structured data needed for risk assessment.

#### 2.2.b Card payments must use CardPayment

❌ Don't use `payment.v1` for 3-D Secure or other card payments.

✅ Instead, use [CardPayment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#cardpayment) for all card payments. Reserve [Payment](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#payment) for Account payments.

**Why this matters:** `CardPayment` carries the card-specific context required for 3-D Secure and card transaction approvals.

#### 2.2.c Don't use Payment to add cards or accounts

❌ Don't use `payment.v1` with a 0 kr (or nominal) amount to add or confirm a payment card or bank account.

✅ Instead, use [ApproveCard](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#approvecard) to add a card, or [ApproveAccount](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#approveaccount) to add an account.

**Why this matters:** `ApproveCard` and `ApproveAccount` present the correct intent to the user and avoid nominal charges and refunds. Using `Payment` for this purpose misrepresents the action.

## 3. Design requirements

### 3.1 One BankID = one button

❌ Don't present multiple BankID buttons based on level of assurance — for example one button for BankID with password and another for BankID with biometrics.

✅ Instead, present a single BankID button that triggers authentication, and follow the [BankID design requirements](https://bankid.no/bedrift/designmanual-knapper) at all times.

**Why this matters:** there is only one BankID brand, and splitting the entry point by level of assurance forces users to choose between options they don't understand. A single, consistently styled button following the design requirements maximises user friendliness and completion rate.