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.
If you are curious about how your consumers would be using iDIN, then you can experiment with CM's iDIN demonstration.
The iDIN system allows you to service several use cases
What you should not do:
Using the credentials provided , you initially have access to dummy data only via our API. The credentials provided by CM are confidential and should not be distributed further. If you have not yet received any credentials, you can request them via this link.
Before starting integration of iDIN into your services, we advise you to read our Merchant Implementation Guide (Dutch). In order to gain access to consumer data, you need to pass the criteria as listed in this merchant implementation guide.
Note that because of bank regulations, you also need a contract with CM and you need to pass CM's business compliance check. This process can take anywhere from a day up to a week, depending on how many other customers need to pass our compliance criteria at any given time. You should therefor get this administrative process started with your CM account manager, well before you want to receive consumer data and before you plan your 'go live' moment.
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.
If you need technical assistance, please contact [email protected]
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.
https://idin.cmtelecom.com/idin/v1.0/directory
Retrieve a listing of all the banks and their identifiers. The result is grouped by country.
{
"merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e"
}
merchant_token
: a guid 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
http status | description |
---|---|
200 | List of banks |
400 | Invalid request |
403 | Authorization required |
default | Any 4xx and 5xx error codes might contain an error response and when present should be handled |
[
{
"country": "string",
"issuers": [
{
"issuer_id": "RABONL2U",
"issuer_name": "Rabobank"
}
]
}
]
country
: The readable name of the countryissuer_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.Any API call can return an error message
{
"status": 500,
"message": "string",
"code":
}
status
: Response status code, matches the HTTP error codemessage
: 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.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.
{
"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"
}
merchant_token
: a guid 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
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.identity
: Retrieve a uniquely identifying token with the bank for this consumer that is consistent across multiple sessionsname
: Retrieve the name information associated with this consumergender
: Retrieve the gender of this consumeraddress
: Retrieve address information associated with this consumerdate_of_birth
: Retrieve the birthdate of the user18y_or_older
: Retrieve if this user is known to be 18 years or olderemail_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.http status | description |
---|---|
200 | Succesful transaction |
400 | Invalid request |
403 | Authorization required |
default | Any 4xx and 5xx error codes might contain an error response |
{
"transaction_id": "string",
"issuer_authentication_url": "https://issuerserver/transaction",
"merchant_reference": "string"
}
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 customermerchant_reference
: A private reference id for accounting purposes. Send this together with the transaction_id
when making a Status requesthttps://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.
NOTE: Personal information will only be returned ONCE by this call. If you need the information a second time, you will have to make a NEW iDIN request for the consumer.
{
"merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
"transaction_id": "string",
"merchant_reference": "string"
}
merchant_token
: a guid 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
: The public identifier of the transaction.merchant_reference
: The private reference of the transaction as provided by the Status responsehttp status | description |
---|---|
200 | OK |
400 | Invalid request |
403 | Authorization required |
404 | The transaction could not be found |
default | Any 4xx and 5xx error codes might contain an error response |
{
"status": "success",
"transaction_id": "3645651845961623",
"issuer_id": "INGBNL2A",
"bin": "NLINGB3x4u89498qe4tqjvdaj0",
"name": {
"gender": "male",
"initials": "A",
"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": "[email protected]"
}
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 unspecifiedinitials
: initials of the user. Up to 20 characters.last_name
: last name of the user. Up to 200 characterslast_name_prefix
: name prefix of the user. Up to 10 characters.street
: streetname: Up to 43 charactershouse_number
: /[0-9]{1,5}/
house_number_suffix
: Up to 6 characterspostal_code
: /[0-9]{4}[a-zA-Z]{2}/
city
: Up to 24 characterscountry
: 2 letter identifier of the country. date_of_birth
: 1970-01-0118y_or_older
: is the current user 18 years or older at this moment. Booleantelephone_number
: the phone number is unverified. /[0-9 ()+-]{1,20}/
email_address
: the email address is unverified. Up to 256 characters.POST https://idin.cmtelecom.com/idin/v1.0/qr/create
Use this call to create a new QR code. After this call you should add the link to the QR code image on your website.
{
"merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
"attributes": {
"identity": true,
"name": true,
"gender": true,
"address": true,
"date_of_birth": true,
"18y_or_older": true,
"email_address": true,
"telephone_number": true
},
"entrance_code": "string",
"merchant_return_url": "string",
"language": "nl",
"use_case": "00",
"expiration": "2019-01-01 00:00:00",
"size": 200,
"format": "png"
}
merchant_token
: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78eentrance_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 attacksmerchant_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.use_case
: Used to be able to differentiate between security measures. Supported values are:expiration
: The date and time (in UTC) at which the iDIN QR code expires and can no longer be used to initiate iDIN transactions. Example: 2019-01-01 00:00:00attributes
:
identity
: Retrieve a uniquely identifying token with the bank for this consumer that is consistent across multiple sessionsname
: Retrieve the name information associated with this consumergender
: Retrieve the gender of this consumeraddress
: Retrieve address information associated with this consumerdate_of_birth
: Retrieve the birth date of the user18y_or_older
: Retrieve if this user is known to be 18 years or olderemail_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.
size
: The size of the QR code in pixels. Defaults to 300format
: The format of the QR code. Currently only png
is supported.{
"qr_id": "2cce6c05-057b-4d0e-be78-ca57eba3ff46",
"qr_url": "https://qrcode.idin.nl/qrcode/2cce6c05-057b-4d0e-be78-ca57eba3ff46.png"
}
qr_id
: A public ID for this QR code,qr_url
: The URL of the QR code image.POST https://idin.cmtelecom.com/idin/v1.0/qr/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 retrieve the QR code ID for the user and send it with the transaction_id to retrieve the status.
NOTE: Personal information will only be returned ONCE by this call. If you need the information a second time, you will have to make a NEW iDIN request for the consumer.
{
"merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
"transaction_id": "string",
"qr_id": "string"
}
merchant_token
: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78etransaction_id
: The public identifier of the transaction.qr_id
: The public identifier of the QR code.{
"status": "success",
"transaction_id": "3645651845961623",
"issuer_id": "INGBNL2A",
"bin": "NLINGB3x4u89498qe4tqjvdaj0",
"name": {
"gender": "male",
"initials": "A",
"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": "[email protected]"
}