iDIN
iDIN
PHP

Introduction

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.

Important NOTE: An up to date swagger API specification is available, which provides more details about the calls mentioned in this documentation.

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

post

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

POST Parameters

name in required schema
Directory request body true
  • {
    • "type" : "object",
    • "allOf" : [
      • {
        • "merchant_token" : "string"
        }
      ]
    }

Responses

http status description
200 List of banks
default Any non-compliant request will return an error object

curl -i https://idin.cmtelecom.com/idin/v1.0/directory
     -X POST
     -H "Content-Type: application/json"
     -d "{
 'type' : 'object',
 'allOf' : [
  {
   'merchant_token' : 'string'
  }
 ]
}"
<?php
  // cURL v7.18.1+ and OpenSSL 0.9.8j+ are required
  $parameters = array(
    'data' => json_encode(array(
               "type" => "object",
               "allOf": [
                array(
                 "merchant_token" => "string"
                )
               ]
              )          )
  );

  $url = 'https://idin.cmtelecom.com/idin/v1.0/directory';

  $ch = curl_init();
  curl_setopt_array($ch, array(
     CURLOPT_URL            => $url,
     CURLOPT_HTTPHEADER     => array(
                                 'Content-Type: application/json'
                                 ),
     CURLOPT_HEADER       => TRUE,
     CURLOPT_POST           => true,
     CURLOPT_POSTFIELDS     => $data,
     CURLOPT_RETURNTRANSFER => true
    )
  );
  $result = curl_exec($ch);
  $HeaderInfo = curl_getinfo($ch);
  $HeaderSize=$HeaderInfo['header_size'];
  $Body = trim(mb_substr($result, $HeaderSize));
  $ResponseHeader = explode('\n',trim(mb_substr($result, 0, $HeaderSize)));
  unset($ResponseHeader[0]);
  $Headers = array();
  foreach($ResponseHeader as $line){
      list($key,$val) = explode(':',$line,2);
      $Headers[strtolower($key)] = trim($val);
  }

  var_dump( array(
      'Body' => $Body,
      'Headers' => $Headers
  ));
?>

transaction

post

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

POST Parameters

name in description required schema
Transaction request body Start true
  • {
    • "title" : "Transaction request",
    • "type" : "object",
    • "description" : "Use one or more of identity, name, address, date_of_birth and 18y_or_older to request information\n",
    • "allOf" : [
      • {
        • "merchant_token" : "string"
        }, {
        • "identity" : {
          • "type" : "boolean",
          • "description" : "Retrieve a uniquely identifying token with the bank for this consumer that is consistent accross multiple sessions\n"
          }, "name" : {
          • "type" : "boolean",
          • "description" : "Retrieve the name information associated with this consumer"
          }, "gender" : {
          • "type" : "boolean",
          • "description" : "Retrieve the gender of this consumer"
          }, "address" : {
          • "type" : "boolean",
          • "description" : "Retrieve address information associated with this consumer"
          }, "date_of_birth" : {
          • "type" : "boolean",
          • "description" : "Retrieve the birthdate of the user"
          }, "18y_or_older" : {
          • "type" : "boolean",
          • "description" : "Retrieve if this user is known to be 18 years or older."
          }, "email_address" : {
          • "type" : "boolean",
          • "description" : "Retrieve the email address associated with this consumer."
          }, "telephone_number" : {
          • "type" : "boolean",
          • "description" : "Retrieve the telephone number associated with this consumer."
          }, "issuer_id" : "string",
        • "entrance_code" : "string",
        • "merchant_return_url" : "string",
        • "language" : "string"
        }
      ]
    }

Responses

http status description
200 Succesful transaction
default Any non-compliant request will return an error object

curl -i https://idin.cmtelecom.com/idin/v1.0/transaction
     -X POST
     -H "Content-Type: application/json"
     -d "{
 'title' : 'Transaction request',
 'type' : 'object',
 'description' : 'Use one or more of identity, name, address, date_of_birth and 18y_or_older to request information\n',
 'allOf' : [
  {
   'merchant_token' : 'string'
  },
  {
   'identity' : {
    'type' : 'boolean',
    'description' : 'Retrieve a uniquely identifying token with the bank for this consumer that is consistent accross multiple sessions\n'
   },
   'name' : {
    'type' : 'boolean',
    'description' : 'Retrieve the name information associated with this consumer'
   },
   'gender' : {
    'type' : 'boolean',
    'description' : 'Retrieve the gender of this consumer'
   },
   'address' : {
    'type' : 'boolean',
    'description' : 'Retrieve address information associated with this consumer'
   },
   'date_of_birth' : {
    'type' : 'boolean',
    'description' : 'Retrieve the birthdate of the user'
   },
   '18y_or_older' : {
    'type' : 'boolean',
    'description' : 'Retrieve if this user is known to be 18 years or older.'
   },
   'email_address' : {
    'type' : 'boolean',
    'description' : 'Retrieve the email address associated with this consumer.'
   },
   'telephone_number' : {
    'type' : 'boolean',
    'description' : 'Retrieve the telephone number associated with this consumer.'
   },
   'issuer_id' : 'string',
   'entrance_code' : 'string',
   'merchant_return_url' : 'string',
   'language' : 'string'
  }
 ]
}"
<?php
  // cURL v7.18.1+ and OpenSSL 0.9.8j+ are required
  $parameters = array(
    'data' => json_encode(array(
               "title" => "Transaction request",
               "type" => "object",
               "description" => "Use one or more of identity, name, address, date_of_birth and 18y_or_older to request information\n",
               "allOf": [
                array(
                 "merchant_token" => "string"
                ),
                array(
                 "identity": array(
                  "type" => "boolean",
                  "description" => "Retrieve a uniquely identifying token with the bank for this consumer that is consistent accross multiple sessions\n"
                 ),
                 "name": array(
                  "type" => "boolean",
                  "description" => "Retrieve the name information associated with this consumer"
                 ),
                 "gender": array(
                  "type" => "boolean",
                  "description" => "Retrieve the gender of this consumer"
                 ),
                 "address": array(
                  "type" => "boolean",
                  "description" => "Retrieve address information associated with this consumer"
                 ),
                 "date_of_birth": array(
                  "type" => "boolean",
                  "description" => "Retrieve the birthdate of the user"
                 ),
                 "18y_or_older": array(
                  "type" => "boolean",
                  "description" => "Retrieve if this user is known to be 18 years or older."
                 ),
                 "email_address": array(
                  "type" => "boolean",
                  "description" => "Retrieve the email address associated with this consumer."
                 ),
                 "telephone_number": array(
                  "type" => "boolean",
                  "description" => "Retrieve the telephone number associated with this consumer."
                 ),
                 "issuer_id" => "string",
                 "entrance_code" => "string",
                 "merchant_return_url" => "string",
                 "language" => "string"
                )
               ]
              )          )
  );

  $url = 'https://idin.cmtelecom.com/idin/v1.0/transaction';

  $ch = curl_init();
  curl_setopt_array($ch, array(
     CURLOPT_URL            => $url,
     CURLOPT_HTTPHEADER     => array(
                                 'Content-Type: application/json'
                                 ),
     CURLOPT_HEADER       => TRUE,
     CURLOPT_POST           => true,
     CURLOPT_POSTFIELDS     => $data,
     CURLOPT_RETURNTRANSFER => true
    )
  );
  $result = curl_exec($ch);
  $HeaderInfo = curl_getinfo($ch);
  $HeaderSize=$HeaderInfo['header_size'];
  $Body = trim(mb_substr($result, $HeaderSize));
  $ResponseHeader = explode('\n',trim(mb_substr($result, 0, $HeaderSize)));
  unset($ResponseHeader[0]);
  $Headers = array();
  foreach($ResponseHeader as $line){
      list($key,$val) = explode(':',$line,2);
      $Headers[strtolower($key)] = trim($val);
  }

  var_dump( array(
      'Body' => $Body,
      'Headers' => $Headers
  ));
?>

status

post

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

POST Parameters

name in schema
Status request body
  • {
    • "title" : "StatusRequest",
    • "type" : "object",
    • "allOf" : [
      • {
        • "merchant_token" : "string"
        }, {
        • "transaction_id" : "string",
        • "merchant_reference" : "string"
        }
      ]
    }

Responses

http status description
200 OK
default Any non-compliant request will return an error object
curl -i https://idin.cmtelecom.com/idin/v1.0/status
     -X POST
     -H "Content-Type: application/json"
     -d "{
 'title' : 'StatusRequest',
 'type' : 'object',
 'allOf' : [
  {
   'merchant_token' : 'string'
  },
  {
   'transaction_id' : 'string',
   'merchant_reference' : 'string'
  }
 ]
}"
<?php
  // cURL v7.18.1+ and OpenSSL 0.9.8j+ are required
  $parameters = array(
    'data' => json_encode(array(
               "title" => "StatusRequest",
               "type" => "object",
               "allOf": [
                array(
                 "merchant_token" => "string"
                ),
                array(
                 "transaction_id" => "string",
                 "merchant_reference" => "string"
                )
               ]
              )          )
  );

  $url = 'https://idin.cmtelecom.com/idin/v1.0/status';

  $ch = curl_init();
  curl_setopt_array($ch, array(
     CURLOPT_URL            => $url,
     CURLOPT_HTTPHEADER     => array(
                                 'Content-Type: application/json'
                                 ),
     CURLOPT_HEADER       => TRUE,
     CURLOPT_POST           => true,
     CURLOPT_POSTFIELDS     => $data,
     CURLOPT_RETURNTRANSFER => true
    )
  );
  $result = curl_exec($ch);
  $HeaderInfo = curl_getinfo($ch);
  $HeaderSize=$HeaderInfo['header_size'];
  $Body = trim(mb_substr($result, $HeaderSize));
  $ResponseHeader = explode('\n',trim(mb_substr($result, 0, $HeaderSize)));
  unset($ResponseHeader[0]);
  $Headers = array();
  foreach($ResponseHeader as $line){
      list($key,$val) = explode(':',$line,2);
      $Headers[strtolower($key)] = trim($val);
  }

  var_dump( array(
      'Body' => $Body,
      'Headers' => $Headers
  ));
?>

merchants

get

https://idin.cmtelecom.com/idin/v1.0/merchants/{merchant_token}

GET Parameters

$ref
#/parameters/MerchantToken

Responses

http status description
200 An object with all information about this merchant
default Any non-compliant request will return an error object
curl -i https://idin.cmtelecom.com/idin/v1.0/merchants/{merchant_token}
     -X GET
     -H "Content-Type: application/json"
<?php
  // cURL v7.18.1+ and OpenSSL 0.9.8j+ are required
  $url = 'https://idin.cmtelecom.com/idin/v1.0/merchants/'
         .$merchant_token;

  $ch = curl_init();
  curl_setopt_array($ch, array(
     CURLOPT_URL            => $url,
     CURLOPT_HTTPHEADER     => array(
                                 'Content-Type: application/json'
                                 ),
     CURLOPT_HEADER       => TRUE,
     CURLOPT_RETURNTRANSFER => true
    )
  );
  $result = curl_exec($ch);
  $HeaderInfo = curl_getinfo($ch);
  $HeaderSize=$HeaderInfo['header_size'];
  $Body = trim(mb_substr($result, $HeaderSize));
  $ResponseHeader = explode('\n',trim(mb_substr($result, 0, $HeaderSize)));
  unset($ResponseHeader[0]);
  $Headers = array();
  foreach($ResponseHeader as $line){
      list($key,$val) = explode(':',$line,2);
      $Headers[strtolower($key)] = trim($val);
  }

  var_dump( array(
      'Body' => $Body,
      'Headers' => $Headers
  ));
?>