Overview

The iDIN Directory API allows merchants to retrieve a list of the 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 recognizable.

Generic requirements

Bank selection

For example, a selection list that follows the above requirements might look like this:

Redirect to bank

New windows

iDIN on mobile