Skip to main content
Versionv1
API docs by Redocly

iDIN api (1.0)

Download OpenAPI specification:Download

iDIN is a service by the banks, that allows customers to identify themselves on websites, using the same secure methods as their own bank uses. It is similar to the iDEAL system in how it works and operates.

In addition to identification, it can also provide the connecting website with information about name, address and age of the consumer, if the consumer agrees to provide these.

CM provides a simple API to integrate these options into your website. If you have not yet received a merchant token, you can request one via this link.

How does it work ?

  • The merchant asks the customer to select his bank
  • Start the request for authentication/information
  • The customer is redirected to this bank
  • The customer logs into his bank and approves the transaction
  • The bank sends the customer back to the merchant's (your) landing page
  • The merchant rejoins the customer to his session and retrieves the transaction.
  • You check with the CM iDIN system if the transaction was successful and receive the requested customer information.

Usage

The iDIN system allows you to service several use cases

  • Checking if someone is known with a bank.
    • To see if the user is a legal entity known to a bank
    • To be able to trace the user in case of fraud.
  • Being guaranteed that this is always the same person. For instance
    • To log a user into your system
    • To avoid people registering multiple (fake) accounts in your system.
  • To check if a user is above a certain age limit
  • Retrieving name, address and age information of that person.
    • You should always allow the user to override or change this information, because it is not guaranteed that the information is always correct or complete (someone could have moved but not yet have informed his bank).
    • Match this against your own information and trigger audit signals

Things you should not do:

  • Matching an account in your system on the basis of name/address attributes.
    • Either create a new account after a user identified with iDIN
    • or have the user log into your system before coupling with an iDIN identity

Things you cannot do:

  • Check if an IBAN exists
  • Check if an IBAN belongs to an iDIN user

Directory

Get bank list

Retrieve a listing of all the banks and their identifiers. The result is grouped by country. It is encouraged to cache this list, but you should refresh the list at least once a day.

Request Body schema: application/json
required
merchant_token
required
string <uuid> (MerchantToken)

a UUID string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78e

Responses

Request samples

Content type
application/json
{
  • "merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e"
}

Response samples

Content type
application/json
[
  • {
    }
]

Transaction

Create transaction

Start an authentication or information request

Request Body schema: application/json
required

Start

merchant_token
required
string <uuid> (MerchantToken)

a UUID string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78e

identity
boolean

Retrieve an identifying token (bin) with the bank for this consumer that is consistent across multiple sessions. When false returns a transient_id that will differ per transaction.

name
boolean

Retrieve the name information associated with this consumer

gender
boolean

Retrieve the gender of this consumer

address
boolean

Retrieve address information associated with this consumer

date_of_birth
boolean

Retrieve the birthdate of the user

18y_or_older
boolean

Retrieve if this user is known to be 18 years or older.

email_address
boolean

Retrieve the email address associated with this consumer.

telephone_number
boolean

Retrieve the telephone number associated with this consumer.

issuer_id
required
string (IssuerID) ^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3})...

An identifier for the bank. Used as the value of the

entrance_code
required
string [ 1 .. 40 ] characters ^[a-zA-Z0-9]+$

This is a token that will allow you to rejoin the user to his session when he returns. It can be a maximum of 40 characters and should only contain the characters a-z, A-Z and 0-9. It should only be valid once and needs to be random enough (best use a cryptographically secure random generator) to avoid the possibility of replay attacks.

merchant_return_url
required
string <= 512 characters

The URL the bank should redirect the user to at the end of the flow. The bank will append two query parameters to this URL when returning the user to you, trxid and ec. The latter will contain the value of entrance_code, trxid is the transaction_id that you will receive in this request.

language
string = 2 characters
Enum: "en" "nl"

The 2 character language code in which to return the results. Can be either 'nl' or 'en' for Dutch or English. This is a preferred language, not all banks support all languages.

transaction_reference
string <= 255 characters

A custom reference you can provide that we will add to the transaction, making it possible for you to distinguish transactions.

Responses

Request samples

Content type
application/json
{
  • "merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
  • "identity": true,
  • "name": true,
  • "gender": true,
  • "address": true,
  • "date_of_birth": true,
  • "18y_or_older": true,
  • "email_address": true,
  • "telephone_number": true,
  • "issuer_id": "RABONL2U",
  • "entrance_code": "string",
  • "merchant_return_url": "string",
  • "language": "nl",
  • "transaction_reference": "7defa5c6-7651-45cd-9016-f9027dc4dda9"
}

Response samples

Content type
application/json
{
  • "transaction_id": "stringstringstri",
  • "issuer_authentication_url": "https://issuerserver/transaction",
  • "merchant_reference": "string",
  • "transaction_reference": "7defa5c6-7651-45cd-9016-f9027dc4dda9"
}

Get transaction status

After the user has returned to you via your merchant_return_url, you retrieve the transaction_id from the trxid parameter. You should check that both the entrance_code and the transaction_id match your expectations for that consumer, before you make this status call.

Request Body schema: application/json
required
merchant_token
required
string <uuid> (MerchantToken)

a UUID string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78e

transaction_id
required
string (TransactionID) = 16 characters ^[0-9]{16}$

A token for this transaction. You should store this with your session data, so that at any point, you can make a callback to the iDIN api and retrieve the status and/or results. Note that it is not guaranteed that your user will return to you via your merchant_return_url. A connection might be dropped, a user might accidentally close a window, or he might trigger the back button and return that way. This id is the only way you can retrieve any information in that case.

merchant_reference
required
string <= 35 characters ^[a-zA-Z0-9]+$

The private reference of the transaction

Responses

Request samples

Content type
application/json
{
  • "merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
  • "transaction_id": "stringstringstri",
  • "merchant_reference": "string"
}

Response samples

Content type
application/json
{
  • "transaction_id": "stringstringstri",
  • "transaction_reference": "7defa5c6-7651-45cd-9016-f9027dc4dda9",
  • "issuer_id": "RABONL2U",
  • "status": "success",
  • "bin": "NLINGB3x4u89498qe4tqjvdaj0",
  • "transient_id": "TRANS3x4u89498qe4tqjvdaj0",
  • "name": {
    },
  • "address": {
    },
  • "age": {
    },
  • "telephone_number": "+31612345678",
  • "email_address": "[email protected]"
}

Merchant

Get merchant information

Retrieve information about a merchant

path Parameters
merchant_token
required
string <uuid>

a UUID string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78e

Responses

Response samples

Content type
application/json
{
  • "name": "Example merchant",
  • "status": "onboarding",
  • "services": {
    },
  • "contact": {},
  • "balance": { }
}