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:

Tyro provides a configuration page that must be embedded in an iframe in your app.
Use the pairing API within iClient to pair with a terminal. Using the API (headless pairing) has an additional benefit: the Integration Key is returned once pairing is complete. This is useful for multi-merchant, since the POS can store the MID, TID, and Integration Key for each terminal and simply let the user select which terminal they're using, then supply the MID, TID, and Integration Key for each transaction or claim.

The configuration page (aka pairing page) must not be redirected to a new tab or window. It must be embedded in an iframe in the POS, because the pairing details don't persist across tabs.

Embedded API code example

<!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

<!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 receives and handles the returned response.

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) performs 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 Terminal ID for the terminal.	Yes

responseReceivedCallback (Function) — a callback invoked to indicate the status of a pairing.

Handling the response

Function	Description	Usage required
`responseReceivedCallback`	Callback invoked to indicate status of pairing.	Yes

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

Field	Type	Description	Usage required
`status`	String	Status of the pairing request — `inProgress`, `success`, or `failure`. If `inProgress`, more responses will follow.	Yes
`message`	String	The text message to display to the merchant.	Yes
`integrationKey`	String	The integration key that's returned, to be used to authenticate when transacting.	Yes

Response example

{
"message": "Pairing successful",
"status":"success",
"integrationKey":"***********************"
}

Demo

To learn more about the implementation of headless pairing:

JS Fiddle demo

Don't click Save if you make changes in the JS Fiddle — click Run instead. Clicking Save may break the fiddle's functionality.