# Belfius Reader

The Belfius container in the T1C-JS library is an abstraction layer built on top of the \[Remote Loading] (../belfius-reader.md)

It offers the following functions:

| function        | Input                      | Output       | Description                                                                                                                   |
| --------------- | -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| openSession     | session timeout in seconds | sessionId    | Opens a remote session, the session will be accessible through a session-id. The T1C will keep the session open and reusable. |
| closeSession    | *N/A*                      | *N/A*        | Close a session. When no session is available, a new session will be opened and closed. The T1C will be in its initial state. |
| nonce           | sessionId                  | nonce        | Returns a nonce generated inside a session. A valid sessionID is a required parameter.                                        |
| stx             | sessionId                  | STX response | Execute a STX request. A valid sessionID is a required parameter.                                                             |
| isBelfiusReader | sessionId                  | boolean      | Check if the selected reader is a Belfius Vasco 870 reader                                                                    |

## General <a href="#t1c-jsapi-general" id="t1c-jsapi-general"></a>

### ReaderId <a href="#t1c-jsapi-readerid" id="t1c-jsapi-readerid"></a>

The readerId is passed to the `readerapi` handler object on initialization. For example, opening a session on reader with id `f56c0ffe15a07d09` would look like this:

```javascript
// Initialize a GCL Client
GCLClient.initialize(gclconfig).then(client => {
    // Open a session
    client.belfius("f56c0ffe15a07d09").openSession(10).then(res => {
        // res.data will contain sessionId
    });
});
```

### Callback/Promise <a href="#t1c-jsapi-callback-promise" id="t1c-jsapi-callback-promise"></a>

All function return Promises by default.

If you prefer callbacks, each function also has an optional parameter to pass in a callback function. If a callback function is provided, the function will still return a promise, but the callback function will be called when the promise resolves/gets rejected.

### SessionID is required! <a href="#t1c-jsapi-sessionidisrequired" id="t1c-jsapi-sessionidisrequired"></a>

This is the main difference between the Remote Loading and the Belfius containers. Where the sessionId is optional in the ReLo API, it is**always required** for the Belfius container!

### Response structure <a href="#t1c-jsapi-responsestructure" id="t1c-jsapi-responsestructure"></a>

All responses follow a similar structure:

```javascript
{
    data: any
    success: boolean
}
```

The `success` property indicates whether or not the request was completed successfully. The `data` property is where returned information will be found; the type of `data` varies with each function.

## Detailed Function Overview <a href="#t1c-jsapi-detailedfunctionoverview" id="t1c-jsapi-detailedfunctionoverview"></a>

### openSession <a href="#t1c-jsapi-opensession" id="t1c-jsapi-opensession"></a>

Opens a new session. Returns the sessionId, which will need to be stored by the client application for later use.

#### Interface <a href="#t1c-jsapi-interface" id="t1c-jsapi-interface"></a>

`openSession(timeout?: number, callback?: (error, data))`

#### Parameters <a href="#t1c-jsapi-parameters" id="t1c-jsapi-parameters"></a>

* **timeout** *(optional)*: session timeout in seconds. If not provided, will default to value set in GCLConfig. Must be a number > 0.

#### Output <a href="#t1c-jsapi-output" id="t1c-jsapi-output"></a>

```javascript
{
    data: string // sessionId string
    success: boolean
}
```

### closeSession <a href="#t1c-jsapi-closesession" id="t1c-jsapi-closesession"></a>

Closes \_**all** \_currently open sessions.

#### Interface <a href="#t1c-jsapi-interface.1" id="t1c-jsapi-interface.1"></a>

`closeSession(callback?: (error, data))`

#### Input <a href="#t1c-jsapi-input" id="t1c-jsapi-input"></a>

* none

#### Output <a href="#t1c-jsapi-output.1" id="t1c-jsapi-output.1"></a>

```
{
    success: true
}
```

### nonce <a href="#t1c-jsapi-nonce" id="t1c-jsapi-nonce"></a>

Get nonce for the session.

The value in the HASH field is calculated by the host and verified by the reader. The hash algorithm and length of the HASH field are specified by the selected STX method. The hash value is calculated over the nonce and the message. If the reader calculates a different hash value than specified in the HASH field, then the reader shall discard this STX command.

#### Interface <a href="#t1c-jsapi-interface.2" id="t1c-jsapi-interface.2"></a>

`nonce(sessionId: string, callback?: (error, data))`

#### Input <a href="#t1c-jsapi-input.1" id="t1c-jsapi-input.1"></a>

* **sessionId**: id of the session to use.

#### Output <a href="#t1c-jsapi-output.2" id="t1c-jsapi-output.2"></a>

```javascript
{
    data: string
    success: boolean
}
```

### stx <a href="#t1c-jsapi-stx" id="t1c-jsapi-stx"></a>

Sends an STX command to the reader.

The Vasco secure transfer (STX) model offers an interface towards Vasco client devices with several methods to secure the data to be sent. Such methods include data signing and/or encryption using symmetric or asymmetric algorithms. The host can secure the data towards the reader with the specific method that has been selected during initialization of the secure transfer interface.

#### Interface <a href="#t1c-jsapi-interface.3" id="t1c-jsapi-interface.3"></a>

`stx(sessionId: string, command: string, callback?: (error, data))`

#### Input <a href="#t1c-jsapi-input.2" id="t1c-jsapi-input.2"></a>

* **sessionId**: id of the session to use.
* **command**: STX command string to be sent to reader.

#### Output <a href="#t1c-jsapi-output.3" id="t1c-jsapi-output.3"></a>

```javascript
{
    data: string
    success: boolean
}
```

### isBelfiusReader <a href="#t1c-jsapi-stx" id="t1c-jsapi-stx"></a>

Checks if the selected reader is a Belfius Vasco 870 reader.

This method returns a promise that will resolve to a boolean (or will call the provided callbck function with a boolean). If true, the selected reader is a Belfius reader and it can be used for the STX and Nonce endpoints.

Because Nonce and STX cannot work on non-Belfius readers, these methods will also call the isBelfiusReader method internally, to make sure the selected reader is compatible. If this is not the case, they will return an error.

#### Interface <a href="#t1c-jsapi-interface.3" id="t1c-jsapi-interface.3"></a>

`isBelfiusReader(sessionId: string, callback?: (error, data))`

#### Input <a href="#t1c-jsapi-input.2" id="t1c-jsapi-input.2"></a>

* **sessionId**: id of the session to use.

#### Output <a href="#t1c-jsapi-output.3" id="t1c-jsapi-output.3"></a>

```javascript
belfiusReader: boolean
```
