---
description: '(prerequisite: driver installation neeeded)'
---

# Crelan

{% hint style="warning" %}
Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.
{% endhint %}

## Introduction

This container supports functionality for Crelan bank cards

## Interface

```
export interface AbstractCrelan {
    readApplicationData(callback?: (error: T1CLibException, data: PaymentReadApplicationDataResponse) => void): Promise<PaymentReadApplicationDataResponse>;
    readData(callback?: (error: T1CLibException, data: PaymentReadDataResponse) => void): Promise<PaymentReadDataResponse>;

    allCerts(aid: string, filters: string[] | Options, callback?: (error: T1CLibException, data: PaymentAllCertsResponse | TokenAllCertsExtendedResponse) => void): Promise<PaymentAllCertsResponse | TokenAllCertsExtendedResponse>;
    issuerPublicCertificate(aid: string, callback?: (error: T1CLibException, data: PaymentCertificateResponse) => void): Promise<PaymentCertificateResponse>;
    iccPublicCertificate(aid: string, callback?: (error: T1CLibException, data: PaymentCertificateResponse) => void): Promise<PaymentCertificateResponse>;

    allCertsExtended(aid: string, filters: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
    issuerPublicCertificateExtended(aid: string, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
    iccPublicCertificateExtended(aid: string, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;

    verifyPin(body: PaymentVerifyPinData, callback?: (error: T1CLibException, data: PaymentVerifyPinResponse) => void): Promise<PaymentVerifyPinResponse>;
    sign(body: PaymentSignData, bulk?: boolean, callback?: (error: T1CLibException, data: PaymentSignResponse) => void): Promise<PaymentSignResponse>;
    resetBulkPin(callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
}
```

## Get Crelan Module

Initialise a Trust1Connector client:

```javascript
T1CSdk.T1CClient.initialize(config).then(res => {
  client = res;
}, err => {
    console.error(error)
});
```

Get the Crelan module:

```javascript
var crelan = client.crelan(reader_id);
```

Call a function for the Crelan module:

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

### Obtain the Reader-ID

The constructor for the Crelan 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/core-service#initialize-the-client-library).\
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:

```javascript
var coreService = client.core();
core.readersCardAvailable(callback);
```

This function call returns:

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 (**A**nswer **T**o **R**eset) 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 Crelan card.\
This must be done upon instantiation of the Crelan container:

```javascript
var crelan = client.crelan(reader_id);
```

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

## Reading data

### Applications

List the supported applications on the Crelan card

```javascript
client.crelan(reader_id).readData(callback);
```

An example callback:

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

Response:

```javascript
{
  "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, ...

```javascript
client.crelan(reader_id).readApplicationData(callback);
```

An example callback:

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

Response:

```javascript
{
 "country": "BE",
 "countryCode": "0056",
 "effectiveDate": "190201",
 "expirationDate": "241231",
 "language": "nlen",
 "name": "",
 "pan": "670...001"
}
```



## Extended certificates

You can also fetch the extended versions of the certificates via the functions

```
allCertsExtended(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
iccPublicCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
issuerPublicCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
```

this has the capabilities to return multiple certificates if the token has multiple of this type.

for a single certificate the response looks like:

```json
{
    "success" : true
    "data" : {
        "certificates": [{
            "certificate"?: string,            
            "exponent"?: string,
            "remainder"?: string,
            "parsedCertificate"?: Certificate
        }]
    }
}
```

the `allCertsExtended` returns the following, with the contents of the certificates as the one you can see above;

```json
{
    "success" : true
    "data" : {
        "issuerPublicCertificate": {
            "certificates": [...]
        },
        "iccPublicCertificate": {
            "certificates": [...]
        }
   }
}
```

## 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.

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

client.crelan(reader_id).issuerPublicCertificate(aid, callback);
```

An example callback:

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

Response:

```javascript
{
  "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.

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

client.c(reader_id).iccPublicCertificate(aid, callback);
```

An example callback:

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

Response:

```javascript
{
 "certificate": "dxL8JnkxHneX36tdQCzz...HC3Wpt/qppk008q9OMDgVp0F7NJjCC2mXg3b/qD7c09WFXUwZ+XdkmIefhoZT/kme4QEoD49+ppQiqSeCaRjn6N0OetcjleWkPej8vE0QG4mLlG/edWTVbfMGbED9Kbjf4ooauNnq+iAVwgHedsDpdDWJLhV8sDSLQgZ1B3fMQuyZIaD79+X+H9fbhmJg+j7Lr638srglWM9VlthaWjRbFH2HzNEiQ9sOE20lmj6WM6zdYas9+Z4hcwZqWbeiTeIJDwDc6w==",
 "exponent": "AQAB",
 "remainder": ""
}
```



## 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:

```javascript
var data = {
    "pin": "...."
}
client.crelan(reader_id).verifyPin(data, callback);
```

Response:

```javascript
{
 "verified": 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:

```javascript
var data = {}
client.crelan(reader_id).verifyPin(data, callback);
```

Response:

```javascript
{
 "verified": true
}
```

### Verify PIN - retries left

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

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

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

```javascript
{
  "code": 301,
  "description": "Wrong pin, 2 tries remaining",
  "success": false
}
```

After a second wrong PIN verification:

```javascript
{
  "code": 301,
  "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                                            |
| ----- | ------------------------------------------------------ |
| `301` | Warning: the user can try twice more to verify his PIN |
| `301` | Warning: the user has only 1 retry left                |
| `301` | Error: the PIN is blocked                              |

## Sign

* A Base64-encoded string representation of the digest bytes must be included in the `data` property of the request.
* `txId` will be displayed on the PIN pad
* `language` determines the language displayed on the PIN pad

Additionally, it is possible to bulk sign data without having to re-enter the PIN by adding an optional `bulk` parameter set to `true` to the request. The PIN will not need to re-entered until a request with `bulk` being set to `false` is sent, or the [Bulk PIN Reset](../../token/diplad-belawyer#bulk-pin-reset) method is called.

{% hint style="danger" %}
When using bulk signing, great care must be taken to validate that the first signature request was successful prior to sending subsequent requests. Failing to do this will likely result in the card being blocked.
{% endhint %}

The PIN can provided/entered in the same way as [Verify PIN](../../token/diplad-belawyer#verify-pin)

```javascript
const data = {
    txId: "Tx1",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    language: "fr"
}
const bulk = false;
crelan.sign(data, bulk).then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

```javascript
{
    "success": true,
    "data": {
      "data": "..."
      "cardSignature": "...",
      "readerSignature": "...",
    }    
}
```

## 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:

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

The error object returned:

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

For the error codes and description, see [Status codes](../core/status-codes).
