EMV
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
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);
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
.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
}
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
}
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
}
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
}
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
}
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
}
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
}
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 |
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"
}
Last modified 4yr ago