Pairing, Terminal Information, and iClient Logs

Pairing

Pairing is the process of establishing authentication for the POS to use the terminal. The user provides the Merchant ID (MID) and Terminal ID (TID) and starts the pairing process from the POS. Then on the terminal the Authorise POS process is followed and if successful, the terminal shares its Integration Key with the POS.

There are two ways to implement this. The first is that we provide a configuration page that must be embedded in an iframe in your app. The second is where you use the pairing API within iClient to pair with a terminal. Using the API (Headless Pairing) has an additional benefit which is that the Integration Key is returned once pairing is complete. This has added benefits for Multi Merchant in that the POS can store the MID, TID and Integration Key for each terminal and simply allow the user to select which terminal they are using and then supply the MID, TID and Integration Key for each transaction or claim.

warning

The configuration page aka pairing page, must not be redirected to a new tab or a new window. It must be embedded in an iFrame in the POS because the pairing details do not persist across the tabs.

Embedded API Code Example:

Copy

Copied

<!DOCTYPE html>
<html>
  <head>
    <title>Tyro iClient Pairing API Example</title>
  </head>
  <body>
    <button onclick="showIframe()">Pairing</button>
    <iframe id="iframe" style="display:none" width="600" height="400"></iframe>
    <button onclick="hideIframe()" style="display:none">Close</button>
    <script>
      function showIframe() {
        var iframe = document.getElementById("iframe");
        iframe.src = "https://iclientsimulator.test.tyro.com/configuration.html";
        iframe.style.display = "block";
        var closeButton = document.getElementsByTagName("button")[1];
        closeButton.style.display = "block";
      }
      function hideIframe() {
        var iframe = document.getElementById("iframe");
        iframe.style.display = "none";
        var closeButton = document.getElementsByTagName("button")[1];
        closeButton.style.display = "none";
      }
    </script>
  </body>
</html>

Pairing API Code (Headless Pairing) Example I

Copy

Copied

<!DOCTYPE html>
<html>

<head>
    <title>Tyro Pairing Example</title>
    <script src="https://iclientsimulator.test.tyro.com/iclient-with-ui-v1.js"></script>
    <script>
        var apiKey = "<API KEY>";
        var posProductInfo = {
            posProductVendor: "Acme Co",
            posProductName: "Acme Cloud POS",
            posProductVersion: "1.0.0",
            siteReference: "E.g. my customer ID or address"
        };

        function doPairing() {
            var mid = document.getElementById("mid").value;
            var tid = document.getElementById("tid").value;
            var iclient = new TYRO.IClientWithUI(apiKey, posProductInfo);
            iclient.pairTerminal(mid, tid, function (response) {
                if ("success" == response.status) {
                    console.log("Pairing success: " + JSON.stringify(response));
                    document.getElementById("result").textContent = "Success: " + response.message;
                } else if ("failure" == response.status) {
                    console.log("Pairing failure: " + JSON.stringify(response));
                    document.getElementById("result").textContent = "Failure: " + response.message;
                } else {
                    document.getElementById("result").textContent = response.message;
                }
            });
        }
    </script>
</head>

<body>
    <div class="form">
        <div>
            <label for="mid">Merchant ID:</label>
            <input id="mid" type="text" placeholder="Merchant ID" name="mid">
        </div>
        <div>
            <label for="tid">Terminal ID:</label>
            <input id="tid" type="text" placeholder="Terminal ID" name="tid">
        </div>
        <div>
            <button type="button" onclick="doPairing()">Commence Pairing</button>
        </div>
        <div id="result"></div>
    </div>
</body>

</html>

Pairing API Code (Headless Pairing) Example II

Given below is an example implementation of a pairing request.

The responseReceivedCallback implementation is also specified in a separate function, which is receiving and handling the returned response.

Copy

Copied

var iclient = new TYRO.IClientWithUI(apiKey, posProductInfo);
var merchantId = undefined;
var terminalId = undefined;
var integrationKey = undefined;

var i = 0;

function pair() {
    $("#transaction").hide();
    merchantId = $("#merchantId").val();
    terminalId = $("#terminalId").val();
    if (merchantId != "" && terminalId != "") {
        iclient.pairTerminal(merchantId, terminalId, pairingCallback);
    }
}

var pairingCallback = function (response) {
    console.log(JSON.stringify(response));
    $("#status").html(response.status);
    $("#message").html(response.message);
    $("#key").html(response.integrationKey);
    
    if ("success" == response.status) {
        integrationKey = response.integrationKey;
        $("#transaction").show();
        }
};

Specification

pairTerminal (mid, tid, responseReceivedCallback)

Perform the POS side of the two-part pairing (shared secret exchange) with a terminal.

Parameters:

mid (String) - A Tyro Merchant ID.
tid (String) - A Tyro Terminal ID.

Parameter	type	Description	Required
mid	String	The Tyro Merchant ID for the terminal	YES
tid	String	The Tyro Terchant ID for the terminal	YES

responseReceivedCallback Function - A callback invoked to indicate the status of a pairing.

Handling the response | Terminal Pairing

Function	Description	Usage Required
responseReceivedCallback	Callback invoked to indicate status of pairing	YES

The terminal pairing response is returned in the responseReceivedCallback with the response object containing the following fields

Field	Type	Description	Usage Required
status	String	Status of the pairing request, can be inProgress, success, failure. If inProgress then more responses will follow.	YES
message	String	The Text message to display to the merchant	YES
integrationKey	String	The integration key that is returned, and is to be used to authenticate when transacting.	YES

Response Example

Copy

Copied

{
"message": "Pairing successful",
"status":"success",
"integrationKey":"58b2834fc9296b1ed84ff00bd78e2dd5"
}

Demo

To learn more about the implementation of headless pairing, please click on the below link:

Demo - JS Fiddle

JS Fiddle

Please don't click on the Save button if you make any changes in the JS Fiddle sample app. Instead, please press run if you have made any changes. If you click on save, it may break the functionality of the JS Fiddle.

Terminal Information

The iClient API provides a diagnostic function that allows the POS user to check whether a given terminal is currently paired to and reachable by the POS. This feature can be particularly useful where multiple terminals are paired to the POS and it needs to determine their status. It is also helpful from a diagnostic point of view, as it will help identify any offline, disconnected, or unpaired terminals.

The details of the parameters required to initiate a terminal info request, and the fields required to handle response data, as well as examples demonstrating the usage are given below.

info

terminalInfo() method is only available with headless JS library only. Headless JS library:

Specification

terminalInfo( responseReceivedCallback, requestParams )

Callback invoked when the terminal responds. Called with a single Object containing the following properties:

Parameters:

requestParams (Object) - An object containing the following parameters:

Parameter	type	Description	Required
tid	Integer	Override the configured tid for multi-merchant terminals or if your browser does not support local storage.	YES
mid	Integer	Override the configured mid for multi-merchant terminals or if your browser does not support local storage.	YES
integrationKey	String	Supply the integration key if your browser does not support local storage.	YES

responseReceivedCallback Function - A callback invoked to indicate the status of a pairing.

iClient Logs

Tyro iClient captures all the interactions between the EFTPOS terminal and the POS, along with the POS information, in the form of logs. Tyro customer support may be contacted for assistance in understanding these log messages. The POS has to embed the iClient Logs URL https://iclientsimulator.test.tyro.com/logs.html in an iFrame in their POS or PMS application.

Demo (iClient logs and Embedded Pairing)

To learn more about the implementation of embedded pairing and embedded iClient logs, please click on the below link:

Demo - JS Fiddle