## 🇾đŸ‡Ș Sweden ### BankID BankID is a trusted electronic identification system in Sweden, built on a Public Key Infrastructure (PKI). It provides secure authentication and non-repudiation for online transactions. The system employs two-factor authentication (2FA), combining a personal certificate tied to an individual's social security number with a PIN or password. End-to-end encryption ensures data security. As of September 2021, it was a fundamental part of Sweden's digital infrastructure with over 8 million active users, regulated by the Swedish Financial Supervisory Authority. ### Secure start mandatory > [!NOTE] In order to protect both users and e-services, the secure start of BankID becomes mandatory for all authorities, companies and organizations that use BankID in their e-services. To meet the requirements for secure start you need to implement the changes listed below. By updating to the latest version of ZignSec implementation you will meet all requirements. 1. Use autostart for BankID on the same device 2. Use animated QR code for BankID on another device 3. Remove start with personal identity numbers ## Ways of integration BankID ZignSec provides two ways for implementing Swedish BankID: - **Browser Flow** - The workflow is executed within a ZignSec-controlled browser session. - **API Flow** - A backend without a user interface, suitable for server, mobile, desktop app, or custom scenarios. This flow also includes the Phone Flow - An authentication process when the user is engaged in a telephone conversation. ### Use cases Swedish BankID can be implemented in different ways, depending on the device initiating the flow. The use cases are: - The user aims to authenticate using an app on the **same device** where the BankID app is installed. - The user aims to authenticate using a web browser running on **other device** than the one the BankID app is installed on. For this use case, QR code is the recommended way to trigger an authenitcation. There are three main flows: - [Mobile device](https://www.figma.com/proto/YES4GCyEZsTmygIAl6but5/Mobile?node-id=1%3A164&viewport=1851%2C894%2C0.43621134757995605&scaling=scale-down) - **same device** flow where the app is installed and triggered from the mobile. - [Desktop to mobile device](https://www.figma.com/proto/0PTgHzE4MNujgK8JQiVgzD/Desktop-Mobile?node-id=1%3A998&viewport=676%2C405%2C0.1647709310054779&scaling=scale-down) - **other device** flow where the app is triggered on the desktop to the mobile by QR-code. - [Desktop same device](https://www.figma.com/proto/vbwZ2vAZWoP4KKmoL6flm3/Desktop?node-id=1%3A998&viewport=832%2C405%2C0.15971411764621735&scaling=scale-down) - **same device** flow when the app is installed on the desktop and triggered there. This flow is the least common since most user has the BankID installed on their mobile. > [!NOTE] More than 80% of BankID users are only using the BankID mobile app. ### Autentication or Sign Authenitcation is aimed for identification and sign to be used for digital signatures. But both methods except the same parameters this is a change from previous versions when there was limitations to adding text in the BankID app. ## **Browser Flow** _Execution Sequence_ The initial call triggers the end user's operation - either authenticate or sign. This call instantly activates the authenticate or sign process, and the BankID app is immediately notified to display either authenticate or sign. To avoid continuous polling, consider configuring a webhook for “completed/error”. 1. Request Creation: Set up the POST-request for the product. Use the redirect_url returned in the response to start the browser workflow, identified by sessionid. 2. Running the Login Process: Simply navigate to the redirect_url in a web browser. The workflow may involve specific user interactions and an external device, such as the Swedish mobile BankID, may be necessary. 3. Retrieving Status/Results: Collect status and individual data using the unique workflow sessionid code. Make this call during or after the workflow is completed. The workflow can indicate pending, completed, or error status (exception, user abort, timeout) via a browser redirect to the redirect_success URL and/or through a webhook. Find below the sequence diagram for Browser flow on the same device. ![[BrowserOnSame.jpg]] And here is the sequence diagram for Browser flow on other device. ![[BrowserOnOtherDevice.png.jpg]] #### Swagger for Browser flow - Test BankId SE - Browser Flow: [Swagger UI (zignsec.com)](https://test-gateway.zignsec.com/#/BankId%20SE%20-%20Browser%20Flow) - Production BankId SE - Browser Flow: [Swagger UI (zignsec.com)](https://gateway.zignsec.com/#/BankId%20SE%20-%20Browser%20Flow) #### API Endpoint - Base URL for Test: https://test-gateway.zignsec.com/core/api/sessions/ - Base URL for Production: [https://gateway.zignsec.com/core/api/sessions/](https://gateway.zignsec.com/core/api/sessions/) **Important Note:** For customers using Two-Way SSL certificates, they need to call different endpoints base URL like mentioned below Only available in Production: [https://api-prod.zignsec.com](https://api-prod.zignsec.com "https://api-prod.zignsec.com/") ##### **Authenticate** Used for electronic identifying a person **POST** - BankID SE Auth - Browser Flow Same Device **Endpoint:** /bankidse/browser/same-device/auth **GET** - Get Session Data (BankID SE Auth - Browser Flow Same Device) **Endpoint:** /bankidse/browser/same-device/auth/id **POST** - BankID SE Auth - Browser Flow Other Device **Endpoint:** /bankidse/browser/auth **GET** - Get Session Data (BankID SE Auth - Browser Flow Other Device) **Endpoint:** /bankidse/browser/auth/id ##### **Sign** Used for electronic signatures **POST** - BankID SE Sign - Browser Flow Same Device **Endpoint:** /bankidse/browser/same-device/sign **GET** - Get Session Data (BankID SE Sign - Browser Flow Same Device) **Endpoint:** /bankidse/browser/same-device/sign/id **POST** - BankID SE Sign - Browser Flow Other Device **Endpoint:** /bankidse/browser/sign **GET** - Get Session Data (BankID SE Sign - Browser Flow Other Device) **Endpoint:** /browser/sign/id ### Sample of BankID SE Auth - Browser Flow Other Device ```bash curl -X 'POST' \ 'https://test-gateway.zignsec.com/core/api/sessions/bankidse/browser/auth' \ -H 'accept: application/json' \ -H 'authorization: Your-Subscription-Key' \ -H 'Content-Type: application/json' \ -d '{ "locale": "En", "metadata": { "language": "en", "requirement": { "certificate_policies": [ "1.2.752.78.1.5", "1.2.752.60.1.6" ], "mrtd": false, "personal_number": "194911201111", "pin_code": false } }, "redirect_failure": "https://my_failure_url.com", "redirect_success": "https://my_success_url.com", "relay_state": "my-unique-customer-id", "webhook": "https://my_webhook_url.com" }' ``` ### Request Parameters |Parameter|Type|Description|Required| |---|---|---|---| |locale|string|Preferred Language to Use. Example: En|no| |**metadata**|list|Sign request|yes| |language|string|Decides web form user interface language. The default language is taken from the merchants setting ‘DefaultLanguage’ or EN = English if none is set there. Language can be changed both on a request level here, or on setting level.|no| |requirement|list|RP may use the requirement parameter to describe how a signature must be created and verified. A typical use case is to require Mobile BankID or a certain card reader.|no| |card_reader|Enum: [ Class1, Class2 ]|Class1 - Default. The transaction must be performed using a card reader where the PIN code is entered on the computers keyboard, or a card reader of higher class., Class2 - The transaction must be performed using a card reader where the PIN code is entered on the reader, or a reader of higher class|no| |certificate_policies|string|The oid in certificate policies in the user certificate. List of String. One wildcard "" is allowed from position 5 and forward ie. 1.2.752.78. <br>The values for production BankIDs are: <br>"1.2.752.78.1.1" - BankID on file <br>"1.2.752.78.1.2" - BankID on smart card <br>"1.2.752.78.1.5" - Mobile BankID <br>"1.2.752.71.1.3" - Nordea e-id on file and on smart card. <br>The values for test BankIDs are: <br>"1.2.3.4.5" - BankID on file <br>"1.2.3.4.10" - BankID on smart card <br>"1.2.3.4.25" - Mobile BankID <br>"1.2.752.71.1.3" - Nordea e-id on file and on smart card. <br>"1.2.752.60.1.6" - Test BankID for some BankID Banks <br>If no certificate policies is set the following are default in the production system: <br>1.2.752.78.1.1, 1.2.752.78.1.2, 1.2.752.78.1.5, 1.2.752.71.1.3 <br>The following are default in the test system: <br>1.2.3.4.5, 1.2.3.4.10, 1.2.3.4.25, 1.2.752.60.1.6, 1.2.752.71.1.3 <br>If one certificate policy is set all the default policies are dismissed.|no| |mrtd|boolean|If present, and set to true, the client needs to provide MRTD (Machine readable travel document) information.|no| |personal_number|string|A personal number to be used to complete the transaction. If a BankID with another personal number attempts to sign the transaction, it fails.|no| |pin_code|boolean|Users are required to sign the transaction with their PIN code, even if they have biometrics activated.|no| |theme|Enum Default, Light, Dark|Default - Default theme, Light - Light theme, Dark - Dark theme|no| |user_non_visible_data|string|Data not displayed to the user. base-64 string. 1-200,000 characters after base 64-encoding|no| |user_non_visible_text|string|The text to be displayed and signed. string. 1--40,000 characters after base 64 encoding|no| |user_visible_data|string|The text to be displayed and signed. base-64 string. The text can be formatted using CR, LF and CRLF for new lines. The text must be encoded as UTF-8 and then base 64 encoded. 1--40 000 characters after base 64 encoding|no| |user_visible_data_format|string|If present, and set to simpleMarkdownV1, this parameter indicates that userVisibleData holds formatting characters which, will potentially make the text displayed to the user nicer to look at. For further information of formatting options, please see the [guidelines for formatting text.](https://www.bankid.com/en/utvecklare/guider/formatera-text)|no| |user_visible_text|string|The text to be displayed and signed. string. Converted to UserVisibleData. If both UserVisibleData and UserVisibleText sent, the UserVisibleData will be used. 1--40 000 characters after base 64 encoding|no| |redirect_failure|string|URL to redirect the end-user to on failure. Example: https://my_failure_url.com|no| |redirect_success|string|URL to redirect the end-user to on success. Example: https://my_success_url.com|no| |relay_state|string|Optional Custom Parameter to be included in webhook calls. Example: my-unique-customer-id|no| |webhook|string|Webhook URL where your backend will receive session events. Example: https://my_webhook_url.com|no| #### Sample Response ```json { "data": { "errors": [], "id": "8bd5f1bf-3239-4f17-8ed6-fc620b05884c", "redirect_url": "https://test-gateway.zignsec.com/ui/bankidse/8bd5f1bf-3239-4f17-8ed6-fc620b05884c/?otp=Z_6-zcEsoUane_-Wjcf-DQ&language=en&theme=Light", "status": "GeneratedLink" } } ``` #### Response parameters | Parameter | Description | | ------------ | ---------------------------------------------------------------------------------------- | | id | A unique session identifier generated for each workflow instance | | errors | A JSON array of error conditions | | redirect_url | The URL that the user needs to be redirected to complete the data via the web interface. | #### Sample Response after completing workflow ```json { "errors": [], "id": "ca1d0bcd-94e3-483d-a4dc-f207eb248a29", "result": { "bankIDSE": { "ocspResponse": "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", "orderRef": "458727f9-82f6-45ba-be86-5ca692ff851f", "signature": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+PFNpZ25hdHVyZSB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC8wOS94bWxkc2lnIyI+PFNpZ25lZEluZm8geG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyMiPjxDYW5vbmljYWxpemF0aW9uTWV0aG9kIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvVFIvMjAwMS9SRUMteG1sLWMxNG4tMjAwMTAzMTUiPjwvQ2Fub25pY2FsaXphdGlvbk1ldGhvZD48U2lnbmF0dXJlTWV0aG9kIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS8wNC94bWxkc2lnLW1vcmUjcnNhLXNoYTI1NiI+PC9TaWduYXR1cmVNZXRob2Q+PFJlZmVyZW5jZSBUeXBlPSJodHRwOi8vd3d3LmJhbmtpZC5jb20vc2lnbmF0dXJlL3YxLjAuMC90eXBlcyIgVVJJPSIjYmlkU2lnbmVkRGF0YSI+PFRyYW5zZm9ybXM+PFRyYW5zZm9ybSBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnL1RSLzIwMDEvUkVDLXhtbC1jMTRuLTIwMDEwMzE1Ij48L1RyYW5zZm9ybT48L1RyYW5zZm9ybXM+PERpZ2VzdE1ldGhvZCBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvMDQveG1sZW5jI3NoYTI1NiI+PC9EaWdlc3RNZXRob2Q+PERpZ2VzdFZhbHVlPnFsL2ExdEZsMjNYZ2dHSnZ1OWJTTm8wTEJHNitLKzlLazJkekxLT0xvdmM9PC9EaWdlc3RWYWx1ZT48L1JlZmVyZW5jZT48UmVmZXJlbmNlIFVSST0iI2JpZEtleUluZm8iPjxUcmFuc2Zvcm1zPjxUcmFuc2Zvcm0gQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy9UUi8yMDAxL1JFQy14bWwtYzE0bi0yMDAxMDMxNSI+PC9UcmFuc2Zvcm0+PC9UcmFuc2Zvcm1zPjxEaWdlc3RNZXRob2QgQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGVuYyNzaGEyNTYiPjwvRGlnZXN0TWV0aG9kPjxEaWdlc3RWYWx1ZT43enBCZ3JRN2NNaWlsVDlGaEZGWjk3alNiaXVkYTZYbXZKVVVtUmJ2dXVjPTwvRGlnZXN0VmFsdWU+PC9SZWZlcmVuY2U+PC9TaWduZWRJbmZvPjxTaWduYXR1cmVWYWx1ZT5FU3lmcE5GVk9mOUFZV3daTlk5b2UyeFYvUFRWVlRqbTFhN1hja2c2UVZuMSs4RWxGa3ZLb2IxTnp0NEJ5aFNGL1ArdTRaNUwzR1B6R3BlSnI4NnAycjBxRXdVcGxEaWpWNmtiamhDL3l6ek84aFZ5eSs5ZTBCSzRIWnNycEs5cHJ0c3ZBdVlxcFNGQzBBckQ2UVFoYXd6QXVlS0RPOWRTcGY0MWNyVlNtT29PTWJLVTh0VFVLR3ZwbGZ4alRRQVpoS0JDTHFvNnhNSEQ0ZVVuQS9QNGtFLzZHOU9FZnNsZGJPTlk2UkFFaG1HZXZUK0o1dFJBTWlSbkdGcEtxd3BGdFdqdEw5UHVJVXc0Y1pxQXhZLzZIT1VZU2xIT0dNM2pnRFFXUTF0aHgrbVdES3VUWDczdmRYSjFRUCs5bG5aM2xOMEoxN21vVnQ1bmFGY1N1cjRmd3c9PTwvU2lnbmF0dXJlVmFsdWU+PEtleUluZm8geG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyMiIElkPSJiaWRLZXlJbmZvIj48WDUwOURhdGE+PFg1MDlDZXJ0aWZpY2F0ZT5NSUlGYkRDQ0ExU2dBd0lCQWdJSVE5OUxFSW5GakRFd0RRWUpLb1pJaHZjTkFRRUxCUUF3ZURFTE1Ba0dBMVVFQmhNQ1UwVXhIVEFiQmdOVkJBb01GRlJsYzNSaVlXNXJJRUVnUVVJZ0tIQjFZbXdwTVJVd0V3WURWUVFGRXd3eE1URXhNVEV4TVRFeE1URXhNekF4QmdOVkJBTU1LbFJsYzNSaVlXNXJJRUVnUTNWemRHOXRaWElnUTBFeElIWXhJR1p2Y2lCQ1lXNXJTVVFnVkdWemREQWVGdzB5TXpFd01qTXlNakF3TURCYUZ3MHlOREV3TWpNeU1UVTVOVGxhTUlITk1Rc3dDUVlEVlFRR0V3SlRSVEVkTUJzR0ExVUVDZ3dVVkdWemRHSmhibXNnUVNCQlFpQW9jSFZpYkNreEVUQVBCZ05WQkFRTUNFVnlhV3R6YzI5dU1SVXdFd1lEVlFRcURBeEZjbWxySUV4bGJtNWhjblF4RlRBVEJnTlZCQVVURERFNU5Ea3hNVEl3TVRFeE1URStNRHdHQTFVRUtRdzFLREl6TVRBeU5DQXdPUzR4TlNrZ1JYSnBheUJNWlc1dVlYSjBJRVZ5YVd0emMyOXVJQzBnUW1GdWEwbEVJSEREcFNCbWFXd3hIakFjQmdOVkJBTU1GVVZ5YVdzZ1RHVnVibUZ5ZENCRmNtbHJjM052YmpDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTVJlU3BMbjd0MWlGTjJwU3lDMmJGcmdhOU9MVklOUHBhQ0F1RjZDTEpnek8ydlAvZ2xGNmZlTTdsZ1Bqdnd0TURJVmp2MGNreGJUanJ4eGJsdmh0UGFld24veUZHNUxwZnkvdTFvQS9DZXF4SDRSTEhVWnYrWS9nQXBIM1ptblN2TGFDcWFQTlpsZnpEL2d5a09DZExGRlpvRk8rbVBZREovall6UzJlWktWSndtOEVHTlJNQmdZQ2c3aVJDd0dDTHFacnJBSXYwVkZSVWJvYmtQMWNRaVBkb04rTzF3YnFaMlVpdmFZOXp3MWtkRTF1VWpNekV0SGtHa2F6bkFiTEpoMHpvRDYxYTBoTXJtZVJrSE5DNjZ1L0VGMGdmWGQ4S0xoOEN6L0JaTDhQTUVJUUNUM0VHcU9yS0h5ek4xaTNicHIyd2NaaFVlVEtTM1hpUXVZTkswQ0F3RUFBYU9Cb3pDQm9EQTdCZ2dyQmdFRkJRY0JBUVF2TUMwd0t3WUlLd1lCQlFVSE1BR0dIMmgwZEhBNkx5OTBaWE4wTG5KbGRtOWpZWFJwYjI1emRHRjBkWE11YzJVd0VRWURWUjBnQkFvd0NEQUdCZ1FxQXdRRk1BNEdBMVVkRHdFQi93UUVBd0lIZ0RBZkJnTlZIU01FR0RBV2dCUmdlbjJuV1lPTW42U3hGK29OUTBPVlErYVovVEFkQmdOVkhRNEVGZ1FVTFdNMTltdE5pelpRTTZDWjVzRWVydGtoSXpnd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dJQkFDYjlldHMydGlqcUJIUDk4L0lRVit0VnFhejNxcUtNdjhXeXFyalNxYnhBdWJ2MWNFYkhiVjBsdVJLOXBIelRSWm9pdHhYMG45UXhnbDJmSkV6VjVJbDh5d3JqVldjSU5nemhyVWdmc2x3K3ZneFFwUnpvSVBVaVYvUU5iOXEyZ1dHWks5ZGM0RHZ2dHk5c3BMZFQ0ZmVvUWxHT3R3L1dOMDdTZkpoaUpjS0NieEl2MlJmaERlaHJkcllHeUVBRnB1bkQrZ2ZpcmxMazZ4WU9ERDNkbHdpdEJOM2Z3OHRaMzF2TzZFTmsrUXBXUmhjUXdERm5UYU5wbytMVEZXLytLRXNHemQ0TENqVW42V3MvdUMwbU1lL1VyemRrTnVtV1BvZmRPV0tzWXdYOHY2NEJaWDRQd0FnQmxYMVZlZGZrdUczSkhFb21jdjlkWTJuTVNLRmFqN0tLQjBVcTEwUUJ5MGJMQkhMaUdweFJJQ3lhMVd0em9jcGc4RFErTmNjeXZVazBVTjNnejlnbm4xZkJ6Z2xrdXo1MVMxK1FhSmhkZmN2cG9kVktXMkc5eis5UGlkMHlSbHlxWk8xQzRabDdGc2MwL0hoYVlQVVowSWdKckZyR1VrWUhwcHpSeDJvb3oxa3YvdERBQk1WVVRTNXo4RFNUVzNHc1Q0bHFVcEw3b1ZKQ2xqNzFQOTJLbWsxVXhUaHZSU2NZNVVFZVRZZTcxZXpwUEUyQlRlR29GNDNnbE1lNFZRMUZXbm1ZWFlYOE9HUjVxMVNoeFdidU0zRzIzRUxMUnllWlRnUDh3WGJlblAzV3lrMHFzMFNQRTNYSDlXSFpLUTBEU1EvbStVd3FTUG04MEQ2dXZtUHAzK3UraWZpbzFOYjFqbmlhUzZ2MVhZY1NOekJlWkIzWDwvWDUwOUNlcnRpZmljYXRlPjxYNTA5Q2VydGlmaWNhdGU+TUlJRjNqQ0NBOGFnQXdJQkFnSUlGblpWeWVobVhZd3dEUVlKS29aSWh2Y05BUUVOQlFBd2JqRUxNQWtHQTFVRUJoTUNVMFV4SFRBYkJnTlZCQW9NRkZSbGMzUmlZVzVySUVFZ1FVSWdLSEIxWW13cE1SVXdFd1lEVlFRRkV3d3hNVEV4TVRFeE1URXhNVEV4S1RBbkJnTlZCQU1NSUZSbGMzUmlZVzVySUVFZ1EwRWdkakVnWm05eUlFSmhibXRKUkNCVVpYTjBNQjRYRFRFeE1Ea3lNakUwTWpFeE5Gb1hEVE0wTVRJd01URTBNakV4TkZvd2VERUxNQWtHQTFVRUJoTUNVMFV4SFRBYkJnTlZCQW9NRkZSbGMzUmlZVzVySUVFZ1FVSWdLSEIxWW13cE1SVXdFd1lEVlFRRkV3d3hNVEV4TVRFeE1URXhNVEV4TXpBeEJnTlZCQU1NS2xSbGMzUmlZVzVySUVFZ1EzVnpkRzl0WlhJZ1EwRXhJSFl4SUdadmNpQkNZVzVyU1VRZ1ZHVnpkRENDQWlJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dJUEFEQ0NBZ29DZ2dJQkFJVzBEUG9wTEVodGF3VlJ3TnJFNDMxR1ZzaC9IbldWc1hkZ09qelVzRDdRRDMwL3RmT0hST1FpOW5MdURXa1kxZkVVeFowNllxNUx0Uk9vRnBrVFE2U1JpMlJnaVVrdUNOcU1Fd3NqMmVpYTdLaFlSSWsvWEpra0ZwMUJ2RTYySTYzdnRVelp6UzY5SEFzTU5QbGZkTFUycElaMkFuZDJRSjJkQzB4aW1tRmpZNWs1L3o3L05rM0pHQmJheExIL1g2emhjTnFPcHIyU3J2OUcrbGsrR3Z5N2hRTEltTkxSVis0RzNtYWxIajZRTSt3RGNSS3ZUNFYraVJkdnpQOW84MDMvZytHTDVxaXVmVzZSZFQrMmx3R2lmUDJkM3N1TDc5dUdXMUhPOHFiaWkvaTRIVHhEZnRLZFhGc2xGclhmUisrUVVVNEIrdjZReWI0ckYzcWhEZmVha2dmTDh1emZ0TXRUTVJsb3d4SWIwOGp4Q2VoQ1NhWTBDTUJIUVRTMEx0WDFDL1ZqTTZVYmJwU2EyODB6U0wreFhsUzdTNzI3c0pCNzIyZnpXUjMvTlNwM01aVGJFMFFBcU1URU5ZNHBmd2MvbFh3Vm44VHZBTncxRkl4RTdpa3dJQk1GU282ZVgyVUREejlhaTZkelJyWWZ0STQ0RXRMVHYzS1Y1VURXY0lic1JCdmxnQlFxcXVwaGN1UlZ2MWE2WG85eGVIMitvK0Jzcitzb3VtaUM2eklGdVV1QnhCNHVxc1NxZVZRRmtJYWVwaW53aFg1Q0pCWkxjT1JhTVpGNkkxa0d2RURaT1ZZWE9FdDlQV2cvU3NTY0dNK3NmMjUxMEd6MGYyb21Rak9MNUJlemRZWUtOQXd6aXo5VTFJcjFWcHZ6a0pGNFNBM1cwNWNtampLWkFnTUJBQUdqZGpCME1CMEdBMVVkRGdRV0JCUmdlbjJuV1lPTW42U3hGK29OUTBPVlErYVovVEFQQmdOVkhSTUJBZjhFQlRBREFRSC9NQjhHQTFVZEl3UVlNQmFBRktQeWVIa2RLMFdLeWVIS2xRbmxubS9PeTA3Rk1CRUdBMVVkSUFRS01BZ3dCZ1lFS2dNRUJUQU9CZ05WSFE4QkFmOEVCQU1DQVFZd0RRWUpLb1pJaHZjTkFRRU5CUUFEZ2dJQkFEeGh5eldTem9reUcraFVDcDNVZzdRWnhiTUxLKzZJWXArOGFjUnVUU0ZmcjVtYUgzTXJ5ZDg3L0IyeTlLM2ZXK0ZYUUxwZGhWSG92S0pPQVF5di90M0NBNjJaR3J6aEFYR3FDY1I5U240NGVjS1JKUEU5WkpiemFsbzR3dEtSVXYwNFcyWmdGdW5ZVE41NVRzTm4zYkd6Y0lpQWRkTXE5VE1Ld0lqbDZwNWk2b0lqQW10OS83NVFmN3FRLzF4MjBFVWRzdis4UVBJcDF2bEI4dkF6QXRvKzhiWkZDUnNkTVZMUlJrOTZDb1M1M3Y0YURZWUFNeG1zVGJndkxxVlU1L0NOZlZFZ1ZlU3BGVlN6NmZsYkZNQlpkNUxPUGdsaS9sUko3Rldld1F2clphS2dmSmdkbVVVdkNwaTBlRCsvS0Juc0VKTGJoZG5LL0IraVRvNEE2QndvUis5WGhPUXlOTVRCL1NEdFNZY3pKMzV2RmhaZktKNS8wcHNxWFNKSC8yNXdBNHBlLzM0RVJ6UTFtZ2xhZHQ2Sk9obldmOTJKdzVqZHc3QkZwdGc3bG1Ja0R5WURVKzZSeUVzQXJDaWJJKzI4eUY1L2ZDWkN1VWR3RHc5aUhwb29kZjFoOHQxZ2ZQbm5ta2N3R1RmUGcvZHVVZ2tGd0tZOTdTemZaZ1IwMmhkN3h4bzVwSzc5Y3ppbU1GMkdURnc5U1dTbmxaSzcxZm9ZMjVGelNVSE5tdUdIaEZ6Rzk4QUZJdDBWTHdpVGo4dEplU2pUaTQxaWYyMzd2RE52c2VwdCs4L3R0ODAvZjQ1S3pQTmZXVUIwNi9GR3Iwd2ZvWWdacDRQaTlSUlRYekRhZndqN3FMZHVhZXBSckxjRVVwWFdDR3J1U1V5bHh4Q2hkQlR3VnpabjwvWDUwOUNlcnRpZmljYXRlPjxYNTA5Q2VydGlmaWNhdGU+TUlJRjB6Q0NBN3VnQXdJQkFnSUlVWW1mZHRxdHk4MHdEUVlKS29aSWh2Y05BUUVOQlFBd2JURWtNQ0lHQTFVRUNnd2JSbWx1WVc1emFXVnNiQ0JKUkMxVVpXdHVhV3NnUWtsRUlFRkNNUjh3SFFZRFZRUUxEQlpDWVc1clNVUWdUV1Z0WW1WeUlFSmhibXR6SUVOQk1TUXdJZ1lEVlFRRERCdFVaWE4wSUVKaGJtdEpSQ0JTYjI5MElFTkJJSFl4SUZSbGMzUXdIaGNOTVRFd09USXlNVFF4TlRBeldoY05NelF4TWpNeE1UUXdNVE16V2pCdU1Rc3dDUVlEVlFRR0V3SlRSVEVkTUJzR0ExVUVDZ3dVVkdWemRHSmhibXNnUVNCQlFpQW9jSFZpYkNreEZUQVRCZ05WQkFVVERERXhNVEV4TVRFeE1URXhNVEVwTUNjR0ExVUVBd3dnVkdWemRHSmhibXNnUVNCRFFTQjJNU0JtYjNJZ1FtRnVhMGxFSUZSbGMzUXdnZ0lpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElDRHdBd2dnSUtBb0lDQVFDVHFVN3V4azVRemJYUzZBclhJR1RXTmVaWHo2NWJ6ZGdveGI3OUx2WWgvcDdrY0syNW1BMnR6R3BPM1FTMWVLSkp1ODRHOVVOem00bU1sNmNuZ25YY2p4RVRZaUVxdGlqckE1bWZ6ODY1L1g2VWdPcFg3RGtvdVE4ZDVlRHloSjQ5VXJEcWxyZ29WTXgzMjJrTTBTWjRoZVZlWDgzZTFJU0ZpeXhxWkJLeGgyNXlLWUVaQTRFeklyRGoydGk4Q1JyV1BIQ1RXYUlGcGNkNVR5TWhwVVRQbjREendQaFBHV01STnhnT0FlUDRCU0RCN1I2YXo0cm94N1RQa2Qyc1dHMU9Eai8wSVJQaEpTMWRRMUI3UWlOSFk1OFJqbk5UaEVRS3dkV1dNUE1LUHRoU2QrR0VqTDlHRGFmWXhPc0lyS0ZZd2xZTkJXM0M1bWJlM1QrM2orQXhqNlcySGJnbUpYUEdJdEx1Y3hZMWtQd1Q5TDd1NW5JeGFST21oMXVUd1lxcjlwdUdxNnNvSm5nZ0VTM0s0UEloTTZrYW12bkNDUFhvcVdDQ3J1U0VQVmd5RVpFaTBzaHkrODFRc2ViMWdjOXJZZ1ZyRW5MQk9JeU1xYVR0RXhhRnByWWJ2MWYvQXdXdGpGVWkyWGlTZE44YU1wK2txYmkrMXRLSlVVUExDK0NyZHU5ZkZvLzhsc2xTZGV3K1NuUFZGZVZ6NUNPS2J0NkdURTR4Y0plUnpXNXdRMHc3YityR0xXaEp2d1JKc1M1R1h2cWEzTGc4RXlXaUxKc3d1VEZhRXdQVUR2WkJ2eUZaRVplcnRLZ1piUll2ZXpvOS9ncnd5Qittb3JWckxyeXU5Y2hZRVl3RTU1MHV6eUt0elhVenlnVjhGcFhlOURwbXBPU2ZHTUFVUlFJREFRQUJvM1l3ZERBZEJnTlZIUTRFRmdRVW8vSjRlUjByUllySjRjcVZDZVdlYjg3TFRzVXdEd1lEVlIwVEFRSC9CQVV3QXdFQi96QWZCZ05WSFNNRUdEQVdnQlJLOTZOcUNOb0lPQmNaVXlqSTJxYldOTmhhdWpBUkJnTlZIU0FFQ2pBSU1BWUdCQ29EQkFVd0RnWURWUjBQQVFIL0JBUURBZ0VHTUEwR0NTcUdTSWIzRFFFQkRRVUFBNElDQVFEUDFEb3hqRWpleUcyN3hlYWkrbXB4eEpvcUIxUkRWVEVZODZSZE55bHVVS1FPSWJmS0pNbVgrRFg0dlR1VVFTMzUzOXh6SEt3cGo2Z2sraVpWakYxVW9KdEdwK3F1cmpqYXJPaDQ0cysrczB5V0tpS3JKQkVsb0puOG8rWVhGVDhDN2UxV3RxSlZvYUZkREJDdm9oSnlLMjBQS1M3L25VRzViN0o2aXEzNTE3WXZqYjREOTRMdDBkSE5TZ0QyQklJSG1Oa3BTWVdneWkxc2VhdmhONUFqdGZKcjRwMTAxdTJTc05jTEFyNDJBNWZyYW45dkwyOUhqYU0yTVRVOEwwT3hvSVg4bGdjcFV5OXdjaTdsSFFLT2l3YU9jSUtmQ0MxcU03bE81ejBjNFArbzB6VDYxODN4SlYzcm13MjJHR1lkNDBFQnFXOTdvcUJLMElqK0tsNXN1eWNaNEoycUsxYVZjaVlCWnNCTmxidG16L2s4SHVCeHk5V2JFZVBzWS82MUk1MGZCTFNBa1ZrL1RlYTRqK05OSEoxaW1wN0JvMThhTG84cGxiOWUyaVplSUR6SDF1NjZvMFJGWWJIZG5KRDhDblBlQkxWZ1N2RXFtQlMxMWZnSHI4MS90azVsSnhjS2VqZHNFZnR6R1F4d3VIdy9wamtqb2JJa3hycm9YcGE2aVhva1Z5SDRiZTE2K2YvZERhRWtoOVJmOExoMVVFUVB4eHBDeUlTTWlmSDVwTDc4REtoR25oOFZmaTdFZXNVVjFrNlkzZVZDRncyQ0NLV2N2WHNKYjlRcUxGc0RxSWxXUGg2YkJnTTRhWGZwZTBhckRyZ1lSYmJ4OEw2b3VoeXhBSHdqdHo5aTBsWGV6V01YNWY3UVlSRU1UQzV5QlBOVFRQMmZDTnNvelE9PTwvWDUwOUNlcnRpZmljYXRlPjwvWDUwOURhdGE+PC9LZXlJbmZvPjxPYmplY3Q+PGJhbmtJZFNpZ25lZERhdGEgeG1sbnM9Imh0dHA6Ly93d3cuYmFua2lkLmNvbS9zaWduYXR1cmUvdjEuMC4wL3R5cGVzIiBJZD0iYmlkU2lnbmVkRGF0YSI+PHNydkluZm8+PG5hbWU+WTI0OVJsQWdWR1Z6ZEdObGNuUWdOQ3h1WVcxbFBWUmxjM1FnWVhZZ1FtRnVhMGxFTEhObGNtbGhiRTUxYldKbGNqMDFOVFkyTXpBME9USTRMRzg5VkdWemRHSmhibXNnUVNCQlFpQW9jSFZpYkNrc1l6MVRSUT09PC9uYW1lPjxub25jZT5OQ0RnMklRak1zRUFuWHZKWmE0MUpnOUxsRDA9PC9ub25jZT48ZGlzcGxheU5hbWU+VkdWemRDQmhkaUJDWVc1clNVUT08L2Rpc3BsYXlOYW1lPjwvc3J2SW5mbz48Y2xpZW50SW5mbz48ZnVuY0lkPklkZW50aWZpY2F0aW9uPC9mdW5jSWQ+PHZlcnNpb24+VUdWeWMyOXVZV3c5Tnk0eE5DNHdMakUySmtKaGJtdEpSRjlsZUdVOU55NHhOQzR3TGpFMkprSkpVMUE5Tnk0eE5DNHdMakUySm5Cc1lYUm1iM0p0UFhkcGJqWTBKbTl6WDNabGNuTnBiMjQ5ZDJsdU1URW1aR2x6Y0d4aGVWOTJaWEp6YVc5dVBUSXlTREltZFdocFBXY3pNMnRvTmxKNmVXTm5aR2RLVFZWdmFtRlpUMGh5V1M5WVluQW1iR1ZuWVdONWRXaHBQV2RuWjNKdmN6VnJVRTFWTWxwV2VVNTFPRnBNZDBVcmJIaHBUbFFtWW1WemRGOWlaV1p2Y21VOU1UY3dNRGN5TXpVME1DWlRiV0Z5ZEVOaGNtUmZVbVZoWkdWeVBVMXBZM0p2YzI5bWRDQkpSa1FnTUNaVGJXRnlkRU5oY21SZlVtVmhaR1Z5UFZkcGJtUnZkM01nU0dWc2JHOGdabTl5SUVKMWMybHVaWE56SURFbTwvdmVyc2lvbj48ZW52PjxhaT48dHlwZT5WMGxPUkU5WFV3PT08L3R5cGU+PGRldmljZUluZm8+ZDJsdU1URT08L2RldmljZUluZm8+PHVoaT5nMzNraDZSenljZ2RnSk1Vb2phWU9IclkvWGJwPC91aGk+PGZzaWI+MTwvZnNpYj48dXRiPmNzMTwvdXRiPjxyZXF1aXJlbWVudD48Y29uZGl0aW9uPjx0eXBlPkNlcnRpZmljYXRlUG9saWNpZXM8L3R5cGU+PHZhbHVlPjEuMi4zLjQuNTwvdmFsdWU+PC9jb25kaXRpb24+PC9yZXF1aXJlbWVudD48dWF1dGg+cHc8L3VhdXRoPjwvYWk+PC9lbnY+PC9jbGllbnRJbmZvPjwvYmFua0lkU2lnbmVkRGF0YT48L09iamVjdD48L1NpZ25hdHVyZT4=", "userInfo": { "givenName": "Erik Lennart", "ipAddress": "109.228.185.130", "name": "Erik Lennart Eriksson", "personalNumber": "194911201111", "surname": "Eriksson" } }, "method": "Auth", "userMessage": "NoMessage" }, "status": "Finished" } ``` ### Sample of Error response ```json { "errors": [ { "code": "CANCELLED_BY_USER", "description": "Action cancelled by user" } ], "id": "2cab790d-d0d6-4aa5-9d94-c08caab5dfba", "result": { "method": "Auth", "userMessage": "RFA6" }, "status": "Cancelled" } ``` #### Response Parameters |Parameter|Type|Description| |---|---|---| |errors|list|list of errors see separate table| |id|string|UUID for the session used to fetch the status and result of a session| |result|list|Contains the result of the session more details below.| |ocspResponse|String|The OCSP response. Base64-encoded. The OCSP response is signed by a certificate that has the same issuer as the certificate being verified. The OSCP response has an extension for Nonce. The nonce is calculated as:<br><br>- SHA-1 hash over the base 64 XML signature encoded as UTF-8.<br>- 12 random bytes is added after the hash.<br>- The nonce is 32 bytes (20 + 12).| |orderRef|string|Idprovider UUID for the session, used when conmmunicating issuses with specfic session with provider| |signature|String|The signature as described in the BankID Signature Profile specification. Base64-encoded. XML signature.| |userInfo|Object|Information related to the user:<br><br>- personalNumber: The personal identity number.<br>- name: The given name and surname of the user.<br>- givenName: The given name of the user.<br>- surname: The surname of the user.<br>- ipAddress: The IP address of the user agent as the BankID server discovers it.| |method|String|The method used: "Auth" for Authentication and "Sign" for signature.| |userMessage|String|NoMessage, RFA1, RFA2, RFA3, RFA4, RFA5, RFA6, RFA8, RFA9, RFA13, RFA14, RFA14A, RFA14B, RFA15, RFA15A, RFA15B, RFA16, RFA17, RFA17A, RFA17B, RFA18, RFA19, RFA20, RFA21, RFA22, RFA23| |status|String|Created, GeneratedLink, Pending, Finished, Failed, Cancelled, TimeOut.| #### Errors |Parameter|Type|Description| |---|---|---| |code|string|Error code. Can be used for automatic error processing.| |description|string|Error description. Human readable text.| |details|string|Error details. Might contain technical information.| --- ## API Flow ##### Execution Sequence The opening call initiates the desired end user operation - Authenticate or Sign. 1. This initial call triggers the authenticate or sign process on the BankID backend instantly, alerting the BankID app to display the authenticate or sign page. It's advisable to have a web hook set up for “completion/error” to bypass frequent checks. Establish a login session and launch BankID backend and app for the designated operation - Authenticate or Sign. This will result in a new BankID session token. 2. Commence the login procedure in a BankID app, you find details in the Launching paragraph below. 3. To retrieve the Final Results, ProgressStatus, or Errors, call the API in any of the following ways: -Automate the posting of results to the client's webhooks for success and error, previously registered with ZignSec. -Continually monitor the progress status, errors, and ultimately collect the results. 4. Cancel request terminates an ongoing sign, auth or phone order. This is generally utilized when the user discontinues the order within your service or application Here is the sequence diagrams related to the API flow ![[ApiOnSame.jpg]] ![[ApiOnOther.jpg]] **API Endpoints** - BaseUrl for Test: https://test-gateway.zignsec.com/core/api/sessions/ - BaseUrl for Production: https://gateway.zignsec.com/core/api/sessions/ ##### Authenticate **POST**- BankID SE (Create Authentication Session) **Endpoint:** /bankidse/auth **GET** - Get Session Data (BankID SE (Create Authentication Session)) **Endpoint:** /bankidse/auth/id ##### Sign **POST** - BankID SE (Create Signing Session) **Endpoint:** /bankidse/sign **GET** - Get Session Data (BankID SE (Create Signing Session)) **Endpoint:** bankidse/sign/id #### Sample of a BankID SE Auth Request ```bash curl -X 'POST' \ 'https://test-gateway.zignsec.com/core/api/sessions/bankidse/auth' \ -H 'accept: application/json' \ -H 'authorization: Your-Subscription-Key' \ -H 'Content-Type: application/json' \ -d '{ "locale": "En", "metadata": { "end_user_ip": "127.0.0.1", "requirement": { "certificate_policies": [ "1.2.3.4.5", "1.2.3.4.10", "1.2.3.4.25", "1.2.752.60.1.6", "1.2.752.78.1.1", "1.2.752.78.1.2", "1.2.752.78.1.5", "1.2.752.71.1.3" ], "mrtd": false, "pin_code": false }, "user_non_visible_text": "The text you'\''ll never see", "user_visible_text": "Please authorize the TEST" }, "redirect_failure": "https://my_failure_url.com", "redirect_success": "https://my_success_url.com", "relay_state": "my-unique-customer-id", "webhook": "https://my_webhook_url.com" }' ``` [**Request parameters**](https://developers.zignsec.com/products/bankid-se#request-parameters) **Additional request parameter** |Parameter|Type|Description|Required| |---|---|---|---| |end_user_ip|string|The user IP address as seen by RP. String. IPv4 and IPv6 is allowed. Note the importance of using the correct IP address. It must be the IP address representing the user agent (the end user device) as seen by the RP. If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address. In some use cases the IP address is not available, for instance for voice based services. In this case, the internal representation of those systems IP address is ok to use.|yes| ### Sample Response for BankID API auth This response has a onboarding setting turned. This setting gives you ready examples to add to your code depending on the device. Read more about launching the app in the following part. ```json { "data": { "errors": [], "id": "00e3bbf4-a6b5-48e8-b5bb-2b4417be17f7", "result": { "autoStartToken": "43181c31-a299-4af7-964f-9e84909efb39", "devExamples": { "autoStartUrls": { "android": "https://app.bankid.com/?autostarttoken=43181c31-a299-4af7-964f-9e84909efb39&redirect=null", "ios": "https://app.bankid.com/?autostarttoken=43181c31-a299-4af7-964f-9e84909efb39&redirect=https://translate.google.com/?sl=auto&tl=sv&text=All%20right!&op=translate", "pc": "bankid:///?autostarttoken=43181c31-a299-4af7-964f-9e84909efb39&redirect=null", "pcWithReturn": "bankid:///?autostarttoken=43181c31-a299-4af7-964f-9e84909efb39&redirect=https://translate.google.com/?sl=auto&tl=sv&text=All%20right!&op=translate" } }, "orderRef": "e719a549-dc96-448a-a3fd-77769afd7df3", "qrCodeLink": "https://test-gateway.zignsec.com/ui/bankidseweb/00e3bbf4-a6b5-48e8-b5bb-2b4417be17f7/qr?otp=KpIDtL2pbUCu0pqIkylCSg", "qrStartToken": "88a0a376-8809-42e0-9b90-117252ed3b31" }, "status": "Pending" } } ``` ### Sample response with onboarding setting turned off Same response as above with onboarding setting set to false. Just reach out to us and we will set the setting per your request. ```bash { "data": { "errors": [], "id": "df0bc372-a5c7-482c-8289-be73ad34ffde", "result": { "autoStartToken": "99890334-5ace-451d-8449-00e0a34ef94a", "orderRef": "572941e9-020a-431e-b161-f34589e4770b", "qrCodeLink": "https://test-gateway.zignsec.com/ui/bankidseweb/df0bc372-a5c7-482c-8289-be73ad34ffde/qr?otp=f71NR5LX9EatG4IyGV9HTQ", "qrStartToken": "01c0a40f-5e38-4757-b314-f772430ca264" }, "status": "Pending" } } ``` **Cancel** post BankID SE Cancel Endpoint: /bankidse/cancel ### Sample of cancel request ```bash curl --location 'https://test-gateway.zignsec.com/core/api/sessions/bankidse/cancel' \ --header 'accept: application/json' \ --header 'Authorization: your subscription key' \ --header 'Content-Type: application/json' \ --data '{ "metadata": { "session_id": "18511c63-5849-469b-bfec-6f1229a5997b" } }' ``` ### Sample of response ```json { "errors": [ { "code": "CANCELLED_BY_USER", "description": "Action cancelled by user" } ], "id": "a5a6357d-fc09-46fe-b267-ea6b2980d0ed", "result": { "method": "Auth", "userMessage": "NoMessage" }, "status": "Cancelled" } ``` ### Launching the BankID app Launching from native app on mobile device #### **Android** ```java Intent intent = new Intent(); intent.setAction(Intent.ACTION_VIEW); intent.setData(Uri.parse("https://app.bankid.com/?autostarttoken=&lt;INSERT AUTOSTARTTOKEN HERE&gt;&amp;redirect=null")); intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK); startActivity(intent); ``` There is no guarantee that a valid result will be returned from the BankID app to the application's activity. The application should rely on the collect call to obtain the authentication or signature result. If the BankID app is not installed on the device, an android.content.ActivityNotFoundException is thrown. The application must inform the user and use Message RFA2. On Android 5, the URI should use the "bankid" scheme instead of the "https" scheme. #### **iOS** ```swift let url = URL(string: "https://app.bankid.com/?autostarttoken=<INSERT AUTOSTARTTOKEN HERE>&redirect=<INSERT YOUR LINK HERE>") UIApplication.shared.open(url!, options: [.universalLinksOnly:true]) { (success) in // handle success/failure } ``` If the BankID app is not installed on the device, "false" is returned. The application must inform the user and use Message RFA2. The application must register a universal link or a custom URL scheme to allow the BankID app to relaunch the application. During the Apple App Store review process, the app requires login information to a demo account. This demo account should either not require BankID for login or provide a way to configure the app to use the BankID test environment. #### **Launching the BankID app from a browser** The "redirect" parameter should be placed last in the parameter list. The "autostarttoken" and "rpref" parameters are optional. Parameter names should be in lowercase. If the BankID app is launched without any matching web service calls for authentication or signature, an error message will be displayed in the app. **App links and universal links on Android and iOS** The syntax for the URL is as follows: ```html https://app.bankid.com/?autostarttoken=[TOKEN]&redirect=[RETURNURL] ``` The URL works on Chrome (Android) and Safari (iOS). **Desktop and other mobile browsers** The syntax for the URL is as follows: ```html bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL] ``` The URL works on PCs with all commonly used browsers. There may be variations on different platforms. ### QR code The typical use case for QR codes is when the user uses “Mobile BankID on other device” (see [Use cases](https://developers.zignsec.com/products/bankid-se#use-case)), and there is a security concern that the user does not control both devices. #### **QR code generation** The QR image needs to be updated once every 1-2 sec. (we use 2 sec. on our UI) 1. When our [Browser flow](https://developers.zignsec.com/products/bankid-se#browser-flow) is used, it is handled by ZignSec. 2. When the [Api flow](https://developers.zignsec.com/products/bankid-se#api-flow) is used, your will get a "qrCodeLink" in a response. Customers should display the image "qrCodeLink" and re-render it every 1-2 sec Note: if you navigate to "qrCodeLink" and hit refresh the page you will see new QR each time ### Sample QR html and javascript code Here an example on the htlm and javascript needed to make the QR code animated: #### **html** ```html ... <img id="qr-image" src="..." /> ... ``` #### **javascript** ```javascript const qrCodeLink = '...'; // from bankidse/auth request const imageElement = document.getElementById('qr-image'); const intervalInMilliseconds = 2000; // re-render QR every 2 seconds let t = 0; setInterval(function () { imageElement.setAttribute('src', qrCodeLink + "?t=" + t) t++; }, intervalInMilliseconds) ``` ### Phone Flow The process for initiating an authentication order over the phone and querying its status involves: 1. **Start**: A user converses over the phone, typically with customer service. 2. **Initiation**: Authentication is initiated during the call as needed. 3. **User Action**: The user is instructed to perform a task for authentication, such as entering a one-time password. 4. **Monitoring**: The 'collect' function periodically checks the status of the authentication process. 5. **Confirmation**: Upon successful authentication, the system updates the status, and the user is notified. 6. **Completion**: The call proceeds with the user now authenticated, enabling secure interactions. **POST** - BankID SE (Create Authentication Session over the Phone) **Endpoint:** /bankidse/phone/auth **GET** - Get Session Data (BankID SE (Create Authentication Session over the Phone)) **Endpoint:** /bankidse/phone/auth/id Sample of Phone auth request ```bash curl -X 'POST' \ 'https://test-gateway.zignsec.com/core/api/sessions/bankidse/phone/auth' \ -H 'accept: application/json' \ -H 'authorization: Your-Subscription-key' \ -H 'Content-Type: application/json' \ -d '{ "locale": "En", "metadata": { "call_initiator": "user", "personal_number": "194610241111", "user_non_visible_text": "The text you'\''ll never see", "user_visible_text": "Please authorize yourself for the TEST call" }, "redirect_failure": "https://my_failure_url.com", "redirect_success": "https://my_success_url.com", "relay_state": "my-unique-customer-id", "webhook": "https://my_webhook_url.com" }' ``` **Additional request parameters** |Parameter|Type|Description|Required| |---|---|---|---| |call_initiator|string|Indicate if the user or the RP initiated the phone call.|yes| |personal_number|string|The personal number of the user. 12 digits|yes| ### User Messages When processing an order, the BankID service sends status updates through the Collect API. It's advisable to present this order status , ensuring users stay informed and are notified of any possible errors. ### Recommended user messages | Short name | Swedish | English | Event, status, hintCode or errorCode | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | RFA1 | Starta BankID-appen. | Start your BankID app. | status=pending <br>hintCode=outstandingTransaction <br>hintCode=noClient | | RFA2 | Du har inte BankID-appen installerad. Kontakta din bank. | The BankID app is not installed. Please contact your bank. | The BankID app is not installed in the mobile device. | | RFA3 | ÅtgĂ€rden avbruten. Försök igen | Action cancelled. Please try again. | errorCode=cancelled | | RFA4 | En identifiering eller underskrift för det hĂ€r personnumret Ă€r redan pĂ„börjad. Försök igen. | An identification or signing for this personal number is already started. Please try again. | errorCode=alreadyInProgress | | RFA5 | Internt tekniskt fel. Försök igen. | Internal error. Please try again. | errorCode=requestTimeout <br>errorCode=maintenance (repeatedly) <br>errorCode=internalError | | RFA6 | ÅtgĂ€rden avbruten. | Action cancelled. | status=failed <br>hintCode=userCancel | | RFA8 | BankID-appen svarar inte. Kontrollera att den Ă€r startad och att du har internetanslutning. Om du inte har nĂ„got giltigt BankID kan du skaffa ett hos din bank. Försök sedan igen. | The BankID app is not responding. Please check that it’s started and that you have internet access. If you don’t have a valid BankID you can get one from your bank. Try again. | status=failed <br>hintCode=expiredTransaction | | RFA9 | Skriv in din sĂ€kerhetskod i BankID-appen och vĂ€lj Identifiera eller Skriv under. | Enter your security code in the BankID app and select Identify or Sign. | status=pending <br>hintCode=userSign | | RFA13 | Försöker starta BankID-appen. | Trying to start your BankID app. | status=pending <br>hintCode=outstandingTransaction | | RFA14 (A) | Söker efter BankID, det kan ta en liten stund 
 Om det har gĂ„tt nĂ„gra sekunder och inget BankID har hittats har du sannolikt inget BankID som gĂ„r att anvĂ€nda för den aktuella identifieringen/underskriften i den hĂ€r datorn. Om du har ett BankID-kort, sĂ€tt in det i kortlĂ€saren. Om du inte har nĂ„got BankID kan du skaffa ett hos din bank. Om du har ett BankID pĂ„ en annan enhet kan du starta din BankID-app dĂ€r. | Searching for BankID, it may take a little while 
 If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this identification/signing on this computer. If you have a BankID card, please insert it into your card reader. If you don’t have a BankID you can get one from your bank. If you have a BankID on another device you can start the BankID app on that device. | status=pending <br>hintCode=started <br>The user accesses the service using a personal computer. | | RFA14 (B) | Söker efter BankID, det kan ta en liten stund 
 Om det har gĂ„tt nĂ„gra sekunder och inget BankID har hittats har du sannolikt inget BankID som gĂ„r att anvĂ€nda för den aktuella identifieringen/underskriften i den hĂ€r enheten. Om du inte har nĂ„got BankID kan du skaffa ett hos din bank. Om du har ett BankID pĂ„ en annan enhet kan du starta din BankID-app dĂ€r. | Searching for BankID, it may take a little while 
 If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this identification/signing on this device. If you don’t have a BankID you can get one from your bank. If you have a BankID on another device you can start the BankID app on that device. | status=pending <br>hintCode=started <br>The user accesses the service using a mobile device. | | RFA15 (A) | Söker efter BankID, det kan ta en liten stund 
 Om det har gĂ„tt nĂ„gra sekunder och inget BankID har hittats har du sannolikt inget BankID som gĂ„r att anvĂ€nda för den aktuella identifieringen/underskriften i den hĂ€r datorn. Om du har ett BankID-kort, sĂ€tt in det i kortlĂ€saren. Om du inte har nĂ„got BankID kan du skaffa ett hos din bank. | Searching for BankID:s, it may take a little while 
 If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this identification/signing on this computer. If you have a BankID card, please insert it into your card reader. If you don’t have a BankID you can get one from your bank. | status=pending <br>hintCode=started <br>The user accesses the service using a personal computer. | | RFA15 (B) | Söker efter BankID, det kan ta en liten stund 
 Om det har gĂ„tt nĂ„gra sekunder och inget BankID har hittats har du sannolikt inget BankID som gĂ„r att anvĂ€nda för den aktuella identifieringen/underskriften i den hĂ€r enheten. Om du inte har nĂ„got BankID kan du skaffa ett hos din bank. | Searching for BankID, it may take a little while 
 If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this identification/signing on this device. If you don’t have a BankID you can get one from your bank. | status=pending <br>hintCode=started <br>The user accesses the service using a mobile device. | | RFA16 | Det BankID du försöker anvĂ€nda Ă€r för gammalt eller spĂ€rrat. AnvĂ€nd ett annat BankID eller skaffa ett nytt hos din bank. | The BankID you are trying to use is blocked or too old. Please use another BankID or get a new one from your bank. | status=failed <br>hintCode=certificateErr | | RFA17 (A) | BankID-appen verkar inte finnas i din dator eller mobil. Installera den och skaffa ett BankID hos din bank. Installera appen frĂ„n din appbutik eller https://install.bankid.com | The BankID app couldn’t be found on your computer or mobile device. Please install it and get a BankID from your bank. Install the app from your app store or https://install.bankid.com | status=failed <br>hintCode=startFailed <br>RP does not use QR code. | | RPA17 (B) | Misslyckades att lĂ€sa av QR-koden. Starta BankID-appen och lĂ€s av QR-koden. Kontrollera att BankID-appen Ă€r uppdaterad. Om du inte har BankID-appen mĂ„ste du installera den och skaffa ett BankID hos din bank. Installera appen frĂ„n din appbutik eller https://install.bankid.com | Failed to scan the QR code. Start the BankID app and scan the QR code. Check that the BankID app is up to date. If you don't have the BankID app, you need to install it and get a BankID from your bank. Install the app from your app store or https://install.bankid.com | status=failed <br>hintCode=startFailed <br>RP uses QR code | | RFA18 | Starta BankID-appen. | Start the BankID app. | The name of the link or button used to start the BankID app. | | RFA19 | Vill du identifiera dig eller skriva under med BankID pĂ„ den hĂ€r datorn eller med ett Mobilt BankID? | Would you like to identify yourself or sign with a BankID on this computer, or with a Mobile BankID? | The user accesses the service using a browser on a personal computer. | | RFA20 | Vill du identifiera dig eller skriva under med ett BankID pĂ„ den hĂ€r enheten eller med ett BankID pĂ„ en annan enhet? | Would you like to identify yourself or sign with a BankID on this device, or with a BankID on another device? | The user accesses the service using a browser on a mobile device. | | RFA21 | Identifiering eller underskrift pĂ„gĂ„r. | Identification or signing in progress. | status=pending <br>The hintCode is unknown. | | RFA22 | OkĂ€nt fel. Försök igen. | Unknown error. Please try again. | status=failed <br>The hintCode is unknown. <br>An error occured. The errorCode is unknown. | | RFA23 | Fotografera och lĂ€s av din ID-handling med BankID-appen. | Process your machine-readable travel document using the BankID app. | status=pending <br>hintCode=userMrtd | ### Recommended terminology |Description|Swedish|English| |---|---|---| |Mobile BankID|Mobilt BankID|Mobile BankID| |BankID Security Application for mobile devices|BankID-appen|The BankID app| |BankID Security Application for PCs|BankID-appen eller BankID-programmet|The BankID app| |Security code, password, PIN|SĂ€kerhetskod (för Mobilt BankID) <br>Lösenord (för BankID pĂ„ fil) <br>PIN (för BankID pĂ„ kort)|Security code (for Mobile BankID) <br>Password (for BankID on file) <br>PIN (for BankID on card)| |Sign|Skriva under|Sign| |Signature|Underskrift|Signature| |Identify|Identifiera|Identify| |Identification/authentication|Identifiering|Identification| ## Test BankID SE To get started, 1- Download the BankID app to your phone, or the program BankID Security Application to your computer. 2- Note that a [reconfiguration](https://www.bankid.com/en/utvecklare/test/skaffa-testbankid/testbankid-konfiguration) of the Bankid app is required 3- Move ahead in this [test guide](https://www.bankid.com/en/utvecklare/test/skaffa-testbankid) and follow the instructions to get a BankID for test. All details are mentioned in the [BankID Test website](https://www.bankid.com/en/utvecklare/test); Here you find a [demo](https://demo.bankid.com/) and more information on how to [integrate](https://www.bankid.com/en/utvecklare/guider/teknisk-integrationsguide) the Swedish BankID. You can use one of these [test users list](https://skatteverket.entryscape.net/store/9/resource/162) ***Note that you can not use the test BankID app and real BankID app at the same device.