BankID integration made easy

These are instructions for integrating Swedish BankID that aim to be as succinct as possible. They should cover the needs of 99% of BankID integrations.

For a complete reference, refer to the official documentation available at bankid.com.

It's assumed that you are familiar with how BankID works from the users point of view. Armed with that knowledge, you should have all the important parts up and running within a couple of hours. Let's go.

Obtaining a test BankID

You will need a test BankID to be able to test your integration on the testing environment. As far as I know, you can't have both a test ID and your normal one installed on the same device, so you will need a dedicated testing device. For iOS you will use the regular client with some reconfiguring, but for Android you will have to install a custom APK that you can find here.

The instructions for installing the test identity can be found here. Complete this step before you move on with the guide.

Setting up your request agent

You have to configure your request agent to use the client SSL certificate provided by BankID. The specifics of how to do that will depend on your environment.

BankID provides a certificate in PFX format for use with the test environment, available here. The passphrase for this file is qwerty123. Switching to production later is a matter of using a different file (that your issuing bank will provide).

The public keys that you will be using to validate the identity of the responding server are:

Test

Prod

All three of those files (pfx, prod key, test key) are included in this repo, in the cert folder.

After you've configured the http agent, you're ready to start making API calls.

All calls are made as HTTP POST
Must include the header Content-Type: application/json
All parameters should be sent as JSON in the request body
For all the methods covered below, calling them is a matter of making a POST request to BASE_URL/METHOD_NAME

The base URL for the test environment is https://appapi2.test.bankid.com/rp/v5, and production is located at https://appapi2.bankid.com/rp/v5. These may not be the most current ones when you're reading this, but they should remain available indefinitely at the given locations.

Authentication

To initiate authentication, call the auth endpoint (for example https://appapi2.test.bankid.com/rp/v5/auth) with the following parameters.

Name	Required	Example	Description
endUserIp	Yes	`"213.112.83.16"`
personalNumber	Yes*	`"198006211414"`	Required for the "other device" flow. For "same device" it's optional.
requirement	No	`{}`	Object containing various flags. For "same device" flow, pass `certificatePolicies: ['1.2.752.78.1.5']`. Another useful requirement is `allowFingerprint: true`. You probably won't ever need any of the other possible fields.

Making this call will trigger the authorization flow in the users BankID app.

Signing

To initiate signing, use the sign endpoint.

Name	Required	Example	Description
endUserIp	Yes	`"213.112.83.16"`
userVisibleData	Yes	`"SmFnIGludHlnYXIgYXR0IGphZyB2aWxsIHNrcml2YSBww6UgZG9rdW1lbnRldC4="`	Base64 encoded string containing the text you want the user to sign.
personalNumber	Yes*	`"198006211414"`	See `auth`.
requirement	No	`{}`	See `auth`.

Making this call will trigger the signing flow in the users BankID app.

Launching the native client

The auth and sign calls return an autoStartToken that can be used to construct a url that can be launched on the users device and picked up by the BankID app, if it is installed.

On iOS, the url should be constructed like this:

https://app.bankid.com/?autostarttoken=[AUTOSTART_TOKEN_HERE]&redirect=null

On any other device, use this format:

bankid:///?autostarttoken=[AUTOSTART_TOKEN_HERE]&redirect=null

According to the documentation, the order of the query parameters matters, so don't change it or add any other parameters.

The brackets around the autoStartToken should be included. In other words, this is a valid url:

bankid:///?autostarttoken=[bdaccd84-6a98-4276-ba70-35e944b704af]&redirect=null

And this is not:

bankid:///?autostarttoken=bdaccd84-6a98-4276-ba70-35e944b704af&redirect=null

Polling for results

Both the sign and auth endpoints return objects that contain the fields autoStartToken and orderRef. You will need to poll the collect method to retrieve the status of an ongoing operation.

Documentation states that you should call collect every two seconds but specifically not more often than once per second.

The collect method takes a single parameter – orderRef – and returns two out of three values: status, hintCode and completionData.

If status is pending, keep polling. If status is complete or failed, the flow has finished. For failed and pending orders, hintCode will provide more information on the reason/state. For completed orders, completionData will be an object containing information on the user.

Cancelling an ongoing order

Call cancel with a single parameter – orderRef. Any ongoing orders must be cancelled before the user can start a new order.

Tying it together

Those four methods, auth, sign, collect, and cancel are all you need to get your integration working. Once you get this far though, you'll need to refer to the official docs to ensure you're in compliance with all of the specific requirements therein. For example, certain failstates require you to display specific error messages, and certain data must always be persisted to disk.

fiso/smooth-bankid