EMV

Introduction

This container supports functionality for EMV "chip and PIN" bank cards, including:

• VISA, MasterCard, Amex, CB and UK Post Office Account contact cards

• PayWave (VISA) and PayPass (MasterCard) contactless cards

Get EMV container object

For more information on how to configure the T1C-JS client library see Client Configuration. Initialize a gclClient:

GCLLib.GCLClient.initialize(config, function(err, gclClient) {
    // gclClient ready to use
});

Get the EMV service:

var emv = gclClient.emv(reader_id);

Call a function for the EMV container:

function callback(err,data) {
    if(err){console.log("Error:",JSON.stringify(err, null, '  '));}
    else {console.log(JSON.stringify(data, null, '  '));}
}
emv.pan(callback);

Obtain the Reader-ID

The constructor for the EMV expect as the parameter to be a valid reader-ID. A reader-ID can be obtained from the exposed core functionality, for more information see Core Services. Core services responds with available card-readers, available card in a card-reader, etc. For example: In order to get all connected card-readers, with available cards:

var coreService = gclClient.core();
core.readersCardAvailable(callback);

This function call returns:

{
  "data": [
    {
      "card": {
        "atr": "3B67000000000000009000",
        "description": [
          "Axa Bank (Belgium) Mastercard Gold / Axa Bank Belgium",
          "MisterCash & Proton card",
          "VISA Card (emitted by Bank Card Company - Belgium)"
        ]
      },
      "id": "707e7a6e449f2250",
      "name": "VASCO DIGIPASS 870",
      "pinpad": true
    }
  ],
  "success": true
}

We notice that a card object is available in the response in the context of a detected reader. The reader in the example above is VASCO DIGIPASS 870, has pin-pad capabilities, and there is a card detected with given ATR and some descriptions. An ATR (Answer To Reset) identifies the type of a smart-card. The reader, has a unique ID, reader_id; this reader_id must be used in order to request functionalities for the EMV card. This must be done upon instantiation of the EMV container:

var emv = gclClient.emv(reader_id);

All methods for emv will use the selected reader - identified by the reader_id.

Reading data

Applications

List the supported applications on the EMV card

gclClient.emv(reader_id).applications(callback);

An example callback:

function callback(err,data) {
    if(err){
        console.log("Error:",JSON.stringify(err, null, '  '));
    }
    else {
        console.log(JSON.stringify(data, null, '  '));
    }
}

Response:

{
  "data": [
      {
        "aid": "A0000000048002", 
        "name": "MAESTRO", 
        "priority": 1
      },{
        "aid": "A0000000048008", 
        "name": "MASTERCARD",
        "priority": 1
      }
    ],
  "success": true
}

Application data

The application data contains information of the holder of the card, the validity, the primary account number, ...

gclClient.emv(reader_id).applicationData(callback);

An example callback:

function callback(err,data) {
    if(err){
        console.log("Error:",JSON.stringify(err, null, '  '));
    }
    else {
        console.log(JSON.stringify(data, null, '  '));
    }
}

Response:

{
  "data": {
    "country": "BE", 
    "country_code": "0056", 
    "effective_date": "091101", 
    "expiration_date": "141130", 
    "language": "fr", 
    "name": "LASTNAME/FIRSTNAME", 
    "pan": "6703XXXXXXXXXXXXXX"
  }, 
  "success": true
}

Issuer Public Key Certificate

On some applications there is an issuer public key certificate present. The aid parameter indicates which application you want to use, this can be fetched using the applications endpoint.

// Application ID can be retrieved with the Applications endpoint
var aid = "..."

gclClient.emv(reader_id).issuerPublicKeyCertificate(aid, callback);

An example callback:

function callback(err,data) {
    if(err){
        console.log("Error:",JSON.stringify(err, null, '  '));
    }
    else {
        console.log(JSON.stringify(data, null, '  '));
    }
}

Response:

{
  "data": {
    "data": "base64 encoded data", 
    "exponent": "base64 encoded data", 
    "remainder": "base64 encoded data"
  }, 
  "success": true
}

ICC Public Key Certificate

On some applications there is an icc public key certificate present. The aid parameter indicates which application you want to use, this can be fetched using the applications endpoint.

// Application ID can be retrieved with the Applications endpoint
var aid = "..."

gclClient.emv(reader_id).iccPublicKeyCertificate(aid, callback);

An example callback:

function callback(err,data) {
    if(err){
        console.log("Error:",JSON.stringify(err, null, '  '));
    }
    else {
        console.log(JSON.stringify(data, null, '  '));
    }
}

Response:

{
  "data": {
    "data": "base64 encoded data", 
    "exponent": "base64 encoded data", 
    "remainder": "base64 encoded data"
  }, 
  "success": true
}

Data Filter

Filter

All data on the smart card can be dumped at once, or using a filter. In order to read all data at once:

var filter = [];
gclClient.emv().allData(filter,callback);

Response:

{
  "data": {
    "applications": [
      {
        "aid": "A0000000048002", 
        "name": "MAESTRO", 
        "priority": 1
      },{
        "aid": "A0000000048008", 
        "name": "MASTERCARD",
        "priority": 1
      }
    ],
    "application_data": {
      "country": "BE", 
      "country_code": "0056", 
      "effective_date": "091101", 
      "expiration_date": "141130", 
      "language": "fr", 
      "name": "LASTNAME/FIRSTNAME", 
      "pan": "6703XXXXXXXXXXXXXX"
    }
  },
  "success": true
}

The filter can be used to ask a list of custom data containers. Supported values are: applications, application-data

var filter = ['application-data'];
gclClient.emv().allData(filter,callback);

Response:

{
  "data": {
    "country": "BE", 
    "country_code": "0056", 
    "effective_date": "091101", 
    "expiration_date": "141130", 
    "language": "fr", 
    "name": "LASTNAME/FIRSTNAME", 
    "pan": "6703XXXXXXXXXXXXXX"
  },
  "success": true
}

Verify PIN

Verify PIN without pin-pad

When the web or native application is responsible for showing the password input, the following request is used to verify a card holder PIN:

var data = {
    "pin": "...."
}
gclClient.emv().verifyPin(data, callback);

Response:

{
  "success": true
}

Verify PIN with pin-pad

When the pin entry is done on the pin-pad, the following request is used to verify a given PIN:

var data = {}
gclClient.emv().verifyPin(data, callback);

Response:

{
  "success": true
}

Verify PIN - retries left

After an unsuccessful PIN verification, the error code indicates the number of retries left. For example, when executing:

  $("#buttonValidate").on('click', function () {
      var _body={};
      _body.pin = $("#psw").val(); //only when no pin-pad available
      var emv = connector.emv(reader_id);
      emv.verifyPin(_body, validationCallback);
  });

The following error message will be returned when PIN is wrong:

{
  "code": 103,
  "description": "Wrong pin, 2 tries remaining",
  "success": false
}

After a second wrong PIN verification:

{
  "code": 104,
  "description": "Wrong pin, 1 try remaining",
  "success": false
}

Note that, when the user has at least one retry left, entering a correct PIN resets the PIN retry status.

Code	Description
103	Warning: the user can try twice more to verify his PIN
104	Warning: the user has only 1 retry left
105	Error: the PIN is blocked

Error Handling

Error Object

The functions specified are asynchronous and always need a callback function. The callback function will reply with a data object in case of success, or with an error object in case of an error. An example callback:

function callback(err,data) {
    if(err){
        console.log("Error:",JSON.stringify(err, null, '  '));
    }
    else {
        console.log(JSON.stringify(data, null, '  '));
    }
}

The error object returned:

{
  success: false,
  description: "some error description",
  code: "some error code"
}

For the error codes and description, see Status codes.