BankID Page 1(29) BankID Relying Party Guidelines Version 3.5 2020-10-26 BankID Relying Party Guidelines Version: 3.5 2020-10-26 BankID Page 2(29) BankID Relying Party Guidelines Version 3.5 2020-10-26 1 Introduction .................................................................................................................................. 4 1.1 Versions ............................................................................................................................................... 4 1.2 Terms and Definitions ....................................................................................................................... 4 1.3 How it Works...................................................................................................................................... 5 1.4 Client Platforms ................................................................................................................................. 5 2 Use Cases ...................................................................................................................................... 5 2.1 Basic Use Cases .................................................................................................................................. 5 2.2 Flow of Events .................................................................................................................................... 6 2.3 Exceptions ........................................................................................................................................... 6 3 Launching ..................................................................................................................................... 7 3.1 Launching the BankID App From a Browser ................................................................................. 7 3.1.1 Behaviour in Different Browsers ................................................................................................................ 7 3.1.2 Parameters in the Start URL ....................................................................................................................... 7 3.2 Launching the BankID App from Native App on Mobile Device .................................................. 8 3.2.1 Android ....................................................................................................................................................... 8 3.2.2 iOS .............................................................................................................................................................. 8 4 QR codes ....................................................................................................................................... 9 4.1 Static QR ............................................................................................................................................. 9 4.1.1 Details ......................................................................................................................................................... 9 4.2 Animated QR ...................................................................................................................................... 9 4.2.1 Details ....................................................................................................................................................... 10 5 Technical Requirements ............................................................................................................. 12 6 Recommended User Messages ................................................................................................... 13 7 Production Environment ............................................................................................................ 17 8 Test Environment ....................................................................................................................... 18 9 Information Regarding the Web Service API ........................................................................... 19 9.1 SSL Certificates ................................................................................................................................ 19 9.2 Versions ............................................................................................................................................. 19 9.2.1 Breaking Change ...................................................................................................................................... 19 9.3 Test Environment ............................................................................................................................. 20 9.4 HTTP/1.1 .......................................................................................................................................... 20 9.5 TLS Versions .................................................................................................................................... 20 10 Support ..................................................................................................................................... 20 10.1 Developer Support ........................................................................................................................ 20 10.2 End User Support ......................................................................................................................... 20 11 Recommended Terminology ................................................................................................... 20 12 File Signing ............................................................................................................................. 21 13 Verifying Signatures ............................................................................................................... 21 14 RP Interface Description ........................................................................................................ 22 14.1 /rp/v5.1/auth and /rp/v5.1/sign .................................................................................................... 22 BankID Page 3(29) BankID Relying Party Guidelines Version 3.5 2020-10-26 14.1.1 Parameters for auth and sign ..................................................................................................................... 22 14.1.2 Additional Parameters for sign ................................................................................................................. 22 14.1.3 Response from auth and sign .................................................................................................................... 22 14.2 /rp/v5.1/collect ............................................................................................................................... 23 14.2.1 Parameters for collect ............................................................................................................................... 23 14.2.2 Response from collect .............................................................................................................................. 23 14.2.3 hintCode for Pending Orders .................................................................................................................... 23 14.2.4 hintCode for Failed Orders ....................................................................................................................... 24 14.2.5 completionData for Completed Orders ..................................................................................................... 25 14.3 /rp/v5.1/cancel ............................................................................................................................... 26 14.3.1 Parameters for cancel ................................................................................................................................ 26 14.4 Errors ............................................................................................................................................ 26 14.5 Requirement ................................................................................................................................. 27 14.5.1 Example – allowFingerprint for sign ........................................................................................................ 29 14.5.2 Example – certificatePolicies for auth with Mobile BankID .................................................................... 29 14.5.3 Example – Combined Requirements ........................................................................................................ 29 BankID Page 4(29) BankID Relying Party Guidelines Version 3.5 2020-10-26 1 Introduction This document contains guidelines for Relying Parties (RP, Förlitande Part in Swedish) when using BankID in their own services. Please check https://www.bankid.com/utvecklare/rp-info and verify that you have the latest version of this document. 1.1 Versions Version Date Change 1.x Historical versions < 2.14 Historical versions. Please contact [email protected] if you need this information. 2.14 2017-02-07 A new url must be used to access the service (appapi2.bankid.com). A new issuer certificate must be used as trusted issuer to be able to access appapi2.bankid.com appapi2.bankid.com accepts only TLS1.1 and TLS1.2. Fingerprint supported for Android. Fingerprint supported for signing by using requirementAlternatives. Editorial and minor improvements. 2.15 2017-03-21 The parameter autostarttoken for iOS was wrong. 2.16 2017-11-14