iDIN Directory API

Page contents

• Introduction
  • Key concepts
• Getting started
  • Usage criteria
  • Using the API
• Presentation requirements
  • Generic requirements
  • Bank selection
  • Redirect to bank
  • New windows
  • iDIN on mobile

Introduction

The iDIN Directory API allows merchants to retrieve a list of banks that are part of the iDIN scheme in order to present it to the end-user. Keep in mind that it is not mandatory to use this solution; Signicat can also display the bank list as soon as the iDIN method is started, which makes implementation easier for the merchant. However, if the merchant has some additional requirements or needs, they can use this API to generate the list themselves. Note that the list of banks presented to the end-user must always be the full list included in the API response. For further details about this and other requirements, see the "Presentation requirements" section below.

Key concepts

End-user

The person whose identity will be verified using iDIN.

Issuer

A legal entity which provides digital identities and credentials to its end-users. In the case of iDIN, this role is fulfilled by banks, so "issuer" and "bank" will be used as synonyms in this documentation.

Merchant

An entity which needs to identify its end-users with iDIN. This is the entity that integrates with the iDIN Directory API.

Getting started

Usage criteria

It is not allowed to call the directory service more than once a day (or for each transaction), since the list of banks only changes occasionally. Merchants must also make sure to check if the list has changed at least once a week (required by the iDIN scheme).

Using the API

The API will be used after the end-user selects iDIN as the identification method that they want to use. The process looks like this:

1. The merchant sends a GET request to the API endpoint. The endpoint in pre-production is https://preprod.signicat.com/std/method/demo/?id=idin-directory-service.

2. The merchant uses the response to create the list of banks which will be shown to the end-user.

   **Example response **

   {"Nederland":[{"issuerCountry":"Nederland","issuerName":"Rabobank iDIN issuer simulatie","issuerID":"RABONL2U"}],"Signicat":[{"issuerCountry":"Signicat","issuerName":"Open","issuerID":"openHIO400OIHtest"},{"issuerCountry":"Signicat","issuerName":"Expired","issuerID":"expiredHIO300OIHtest"},{"issuerCountry":"Signicat","issuerName":"Cancelled","issuerID":"cancelledHIO200OIHtest"},{"issuerCountry":"Signicat","issuerName":"Failure","issuerID":"failureHIO500OIHtest"},{"issuerCountry":"Signicat","issuerName":"Success","issuerID":"succesHIO100OIHtest"}]}
   

3. When the end-user selects one of the issuers on the list, the merchant calls the iDIN method as usual, but adds the prefilled.issuer parameter to it. The parameter should be prefilled with the issuerID of the bank chosen by the end-user. For example: &prefilled.issuer=RABONL2U(for SAML) and &login_hint=issuer-RABONL2U(for use with OIDC).

4. Signicat will start the iDIN method with the selected issuer.

Presentation requirements

There are a series of requirements which must be fulfilled by merchants when using the iDIN Directory API to ensure that the end-user experience is consistent and recognisable.

Generic requirements

• It must be clear to the end-user that they are about to authenticate with iDIN. The merchant must clearly indicate which iDIN service they are about to initiate for the end-user.
• An iDIN transaction of any kind must always be recognisable as such to the end-user. This means that the merchant must make sure, when designing their implementation of iDIN, that iDIN and the start of an iDIN process are recognisable as such.

Bank selection

• When the end-user chooses to use iDIN, they should immediately be presented with a selection list where they can pick the bank that they want to use to identify themselves. No intermediate screens should be displayed by the merchant (e.g. login or registration screens).
• All banks must be shown in a dropdown list box as retrieved from the API.
• The first element on the list must be "Kies uw bank" ("Choose your bank") and must be selected by default.
• Afterwards, the banks that the user can choose from must be presented divided by country. The first country must be either the country where the merchant is located or the country that the end-user is expected to be from. The other countries must be listed alphabetically. Within each country, the available entities must be also ordered alphabetically, in the same order as in the API response.
• The merchant is not allowed to remove banks (issuers) temporarily from the selection list or to grey them out. If a merchant learns that a particular bank is currently not available, the merchant can display a message on its website to inform end-users about the fact.
• The "value" field of the items in the bank list must be the issuerID (BIC) of the corresponding bank, because this value is necessary for it to be retrieved correctly.

Redirect to bank

• When the end-user has selected a bank, they should be immediately redirected to the online environment of the selected bank.
• The merchant must perform the redirect to the bank from the browser window where the end-user selected the bank. The complete page of the merchant will be replaced by the complete page of the selected bank; it is not allowed to open the redirect to the bank in a new browser window, but it is allowed to open a new window, with a visible address bar, before the end-user selects their bank from the list.
• Frames used on the merchant's site are allowed. The page of the bank will remove these frames using a frame busting technique. This will allow the end-user to verify whether the transaction is really taking place at the bank chosen from the list of banks. After the redirect to the merchant, the merchant must completely rebuild its page to show its confirmation of reception of the iDIN authentication and attributes.

New windows

• The iDIN authentication can take place in a new browser window or tab as long as the merchant makes it appear at (or before) the moment the end-user chooses the authentication method.
• A new window or tab is only allowed if initiated by the end-user (no pop-ups are allowed).
• The complete transaction process must take place in this window or tab, including the merchant's confirmation of receiving the iDIN authentication and attributes.
• New windows must also contain an address bar to allow the end-user to check the URL and SSL certificate of the bank.
• During the transaction process, it should not be possible for the end-user to initiate another transaction through the merchant's original browser window.

iDIN on mobile

• The iDIN process on mobile may redirect the end-user to a different mobile page or app as part of the transaction.
• The merchant should strive to keep the end-user on one browser page whenever possible, but it is not allowed to make use of an in-app browser in the merchant's app.
• In cases where changing to another app or window is necessary (e.g. when redirecting to the bank), the end-user should be informed beforehand in order to avoid confusion. For example, the merchant could show the following message (in English and Dutch): "You are being redirected to the (mobile) website or the app of your bank" "U wordt doorverwezen naar de (mobiele) website of app van uw bank"