iDIN
iDIN

Introduction

An up to date swagger API specification is available.

iDIN is a service by the banks, that allows customers to identify themselves with 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.

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 merchants (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.

If you are curious about how your consumers would be using iDIN, then you can experiment with CM's iDIN demonstration.

Please let us know if you are interested in alternate methods like OpenID Connect and SAML.

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 user identified with iDIN
    • or have the user log into your system before coupling with an iDIN identity

Integration

Before starting integration of iDIN into your services, we advise you to read our Merchant Implementation Guide.

Visual style

There is a visual style that you are required to follow when using the iDIN brand. The logo's for iDIN can be downloaded here.

directory

Retrieve a listing of all the banks and their identifiers. The result is grouped by country. Note that the iDIN dictates how you should represent these to the consumer. It is encouraged to cache this list, but you should refresh the list at least once a day. It may never be older than 7 days.

post

https://idin.cmtelecom.com/idin/v1.0/directory

Retrieve a listing of all the banks and their identifiers. The result is grouped by country.

  • Note that the iDIN dictates how you should represent these to the consumer.
  • It is encouraged to cache this list, but you should refresh the list at least once a day. It may never be older than 7 days.
  • You should not manipulate this list yourself.

Request

{
  "merchant_token": "283b1550-ed02-4aee-8529-38a8ae90f10e"
}

Parameters

Required:

  • merchant_token: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 283b1550-ed02-4aee-8529-38a8ae90f10e

Response codes

http status description
200 List of banks
400 Invalid request
403 Authorization required

200 Response

[
  {
    "country": "string",
    "issuers": [
      {
        "issuer_id": "RABONL2U",
        "issuer_name": "Rabobank"
      }
    ]
  }
]

Parameters

  • country: The readable name of the country
  • issuer_id: An identifier for the bank. Used as the value of the in bank selector dropdowns. The end user selects a value and iDIN will direct the end user to that bank, so that the user can identify himself. Has the pattern /[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}/
  • issuer_name: The name of the issuing bank intended for display purposes. Used as the content of in the HTML dropdowns.

Error response

Any API call can return an error message

{
  "status": 500,
  "message": "string",
  "code": 
}
  • status: Response status code, matches the HTTP error code
  • message: High level description of the error that occured. This description, when present, can be shown to the end user. It might describe that a bank is not available or that the system is offline, or that an unexpected error occured. In test mode, the API will return more information (targeted at the developer) here then in production mode.
  • code: Low level and/or internal error code describing the error.

transaction

post

https://idin.cmtelecom.com/idin/v1.0/transaction

Use this call to initiate a new transaction. After this call, you should redirect the user to the issuer_authentication_url that you receive in the response of this request.

Request

{
  "merchant_token": "283b1550-ed02-4aee-8529-38a8ae90f10e",
  "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"
}

Parameters

Required:

  • merchant_token: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 283b1550-ed02-4aee-8529-38a8ae90f10e
  • issuer_id: An identifier for the bank which the customer has chosen. /[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}/
  • entrance_code: 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: The place where the issuing 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. When not specified, a default can you be used which you specified with CM.

Optional

  • identity: Retrieve a uniquely identifying token with the bank for this consumer that is consistent across multiple sessions
  • name: Retrieve the name information associated with this consumer
  • gender: Retrieve the gender of this consumer
  • address: Retrieve address information associated with this consumer
  • date_of_birth: Retrieve the birthdate of the user
  • 18y_or_older: Retrieve if this user is known to be 18 years or older
  • email_address: Retrieve the email address associated with this consumer.
  • telephone_number: Retrieve the telephone number associated with this consumer.
  • language: 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.

Responses

http status description
200 Succesful transaction
400 Invalid request
403 Authorization required

200 Response

{
  "transaction_id": "string",
  "issuer_authentication_url": "https://issuerserver/transaction",
  "merchant_reference": "string"
}

Parameters

  • transaction_id: A public token ID for this transaction. You should store this with your session data, so that at any point, you can make a callback to the CM 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 accidently 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.
  • issuer_authentication_url: The location with the issuing bank to which you should now forward the customer
  • merchant_reference: A private reference id for accounting purposes. Send this together with the transaction_id when making a Status request

status

post

https://idin.cmtelecom.com/idin/v1.0/status

After the user has returned to you via your merchant_return_url, you retrieve the transaction_id from the trxid query parameter and the entrance_code from the ec query parameter appended to your merchant_return_url.

Use the entrance_code to rejoin your consumer to the state you have kept. Now retrieve the merchant_reference which you received in the transaction call and send these three elements to make a status request.

Request

{
  "merchant_token": "283b1550-ed02-4aee-8529-38a8ae90f10e",
  "transaction_id": "string",
  "merchant_reference": "string"
}

Parameters

Required:

  • merchant_token: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 283b1550-ed02-4aee-8529-38a8ae90f10e
  • transaction_id: The public identifier of the transaction.
  • merchant_reference: The private reference of the transaction as provided by the Status response

Responses

http status description
200 OK
400 Invalid request
403 Authorization required
404 The transaction could not be found

200 Response

{
  "status": "success",
  "bin": "NLINGB3x4u89498qe4tqjvdaj0",
  "name": {
    "gender": "male",
    "initials": "A",
    "first_name": "Andre",
    "last_name": "Dijk",
    "last_name_prefix": "van"
  },
  "address": {
    "street": "Dijklaan",
    "house_number": 1,
    "house_number_suffix": "b",
    "postal_code": "0000AA",
    "city": "Amsterdam",
    "country": "NL"
  },
  "age": {
    "date_of_birth": "1970-01-01",
    "18y_or_older": true
  },
  "telephone_number": "+31612345678",
  "email_address": "no_reply@cm.nl"
}

Parameters

Only those values that are available will be represented in the response.

  • status: Either open, success, cancelled, failure, expired. If the status is open, then the information was not yet available. Please try again after a few more seconds or fail. If the status is success then you can expect the requested information to be present. A status of cancelled means that the user has cancelled the flow.
  • bin: When identity was requested, this will be a consistent identifier for this user. If identity was not requested, then this will differ every single time. /[a-zA-Z]{6,6}.*/ Up to 256 characters.
  • gender: male, female or unspecified
  • initials: initials of the user. Up to 20 characters.
  • last_name: last name of the user. Up to 200 characters
  • last_name_prefix: name prefix of the user. Up to 10 characters.
  • street: streetname: Up to 43 characters
  • house_number: /[0-9]{1,5}/
  • house_number_suffix:
  • postal_code: /[0-9]{4}[a-zA-Z]{2}/
  • city: Up to 24 characters
  • country: 2 letter identifier of the country.
  • date_of_birth: 1970-01-01
  • 18y_or_older: is the current user 18 years or older at this moment. Boolean
  • telephone_number: the phone number is unverified. /[0-9 ()+-]/
  • email_address: the email address is unverified. Up to 256 characters.