Integration requirements#
On this page
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.
If you have not selected a flow yet, start with the flow overview in Getting started.
At a glance#
| ID | Topic | Not accepted ❌ | Use instead ✅ |
|---|---|---|---|
| 1.1 | Browser-supported channel | CIBA flow | Authorization Code Flow or Iframe Flow |
| 1.2 | Custom UI in CIBA flows | Custom UI mimicking the BankID client | A redirect or iframe flow, or contact us before building any custom UI |
| 1.3.a | Native iOS app redirect | Redirect flow without app_callback_uri | Redirect flow with app_callback_uri |
| 1.3.b | Native app implementation | WebView | Recommendations on Native applications |
| 2.1 | Signing | authentication.v1 | VerifiedConfirmation or another eSigning product |
| 2.2.a | Payments — general | Signing permissions | Payment or CardPayment |
| 2.2.b | Card payments | payment.v1 for card / 3-D Secure payments | CardPayment |
| 2.2.c | Adding cards/accounts | payment.v1 with 0 kr | ApproveCard or ApproveAccount |
| 3.1 | Design requirements | Separate buttons per level of assurance (LoA) | One BankID = one button, following the BankID design requirements (opens in a new tab) |
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 (top-level redirect) or the Iframe Flow.
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 (redirect) or the Iframe Flow instead of building a custom UI.
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 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 permission type or another eSigning product (opens in a new tab).
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 or 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 for all card payments. Reserve 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 to add a card, or 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 (opens in a new tab) 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.