{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Pairing","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"pairing","__idx":0},"children":["Pairing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to implement this:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tyro provides a configuration page that must be embedded in an iframe in your app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"embedded-api-code-example","__idx":1},"children":["Embedded API code example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"<!DOCTYPE html>\n<html>\n  <head>\n    <title>Tyro iClient Pairing API Example</title>\n  </head>\n  <body>\n    <button onclick=\"showIframe()\">Pairing</button>\n    <iframe id=\"iframe\" style=\"display:none\" width=\"600\" height=\"400\"></iframe>\n    <button onclick=\"hideIframe()\" style=\"display:none\">Close</button>\n    <script>\n      function showIframe() {\n        var iframe = document.getElementById(\"iframe\");\n        iframe.src = \"https://iclientsimulator.test.tyro.com/configuration.html\";\n        iframe.style.display = \"block\";\n        var closeButton = document.getElementsByTagName(\"button\")[1];\n        closeButton.style.display = \"block\";\n      }\n      function hideIframe() {\n        var iframe = document.getElementById(\"iframe\");\n        iframe.style.display = \"none\";\n        var closeButton = document.getElementsByTagName(\"button\")[1];\n        closeButton.style.display = \"none\";\n      }\n    </script>\n  </body>\n</html>\n\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pairing-api-code-headless-pairing-example-i","__idx":2},"children":["Pairing API code (headless pairing) example I"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"<!DOCTYPE html>\n<html>\n\n<head>\n    <title>Tyro Pairing Example</title>\n    <script src=\"https://iclientsimulator.test.tyro.com/iclient-with-ui-v1.js\"></script>\n    <script>\n        var apiKey = \"<API KEY>\";\n        var posProductInfo = {\n            posProductVendor: \"Acme Co\",\n            posProductName: \"Acme Cloud POS\",\n            posProductVersion: \"1.0.0\",\n            siteReference: \"E.g. my customer ID or address\"\n        };\n\n        function doPairing() {\n            var mid = document.getElementById(\"mid\").value;\n            var tid = document.getElementById(\"tid\").value;\n            var iclient = new TYRO.IClientWithUI(apiKey, posProductInfo);\n            iclient.pairTerminal(mid, tid, function (response) {\n                if (\"success\" == response.status) {\n                    console.log(\"Pairing success: \" + JSON.stringify(response));\n                    document.getElementById(\"result\").textContent = \"Success: \" + response.message;\n                } else if (\"failure\" == response.status) {\n                    console.log(\"Pairing failure: \" + JSON.stringify(response));\n                    document.getElementById(\"result\").textContent = \"Failure: \" + response.message;\n                } else {\n                    document.getElementById(\"result\").textContent = response.message;\n                }\n            });\n        }\n    </script>\n</head>\n\n<body>\n    <div class=\"form\">\n        <div>\n            <label for=\"mid\">Merchant ID:</label>\n            <input id=\"mid\" type=\"text\" placeholder=\"Merchant ID\" name=\"mid\">\n        </div>\n        <div>\n            <label for=\"tid\">Terminal ID:</label>\n            <input id=\"tid\" type=\"text\" placeholder=\"Terminal ID\" name=\"tid\">\n        </div>\n        <div>\n            <button type=\"button\" onclick=\"doPairing()\">Commence Pairing</button>\n        </div>\n        <div id=\"result\"></div>\n    </div>\n</body>\n\n</html>\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pairing-api-code-headless-pairing-example-ii","__idx":3},"children":["Pairing API code (headless pairing) example II"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given below is an example implementation of a pairing request. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseReceivedCallback"]}," ","implementation is also specified in a separate function, which receives and handles the returned"," ","response."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"var iclient = new TYRO.IClientWithUI(apiKey, posProductInfo);\nvar merchantId = undefined;\nvar terminalId = undefined;\nvar integrationKey = undefined;\n\nvar i = 0;\n\nfunction pair() {\n    $(\"#transaction\").hide();\n    merchantId = $(\"#merchantId\").val();\n    terminalId = $(\"#terminalId\").val();\n    if (merchantId != \"\" && terminalId != \"\") {\n        iclient.pairTerminal(merchantId, terminalId, pairingCallback);\n    }\n}\n\nvar pairingCallback = function (response) {\n    console.log(JSON.stringify(response));\n    $(\"#status\").html(response.status);\n    $(\"#message\").html(response.message);\n    $(\"#key\").html(response.integrationKey);\n    \n    if (\"success\" == response.status) {\n        integrationKey = response.integrationKey;\n        $(\"#transaction\").show();\n        }\n};\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specification","__idx":4},"children":["Specification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pairTerminal(mid, tid, responseReceivedCallback)"]}," performs the POS side of the two-part pairing"," ","(shared secret exchange) with a terminal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Parameters:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mid"]}," (String) — a Tyro Merchant ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tid"]}," (String) — a Tyro Terminal ID."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Tyro Merchant ID for the terminal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Tyro Terminal ID for the terminal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]}]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseReceivedCallback"]}," (Function) — a callback invoked to indicate the status of a pairing."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"handling-the-response","__idx":5},"children":["Handling the response"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Function"},"children":["Function"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Usage required"},"children":["Usage required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseReceivedCallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Callback invoked to indicate status of pairing."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The terminal pairing response is returned in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseReceivedCallback"]},", with the response object"," ","containing the following fields:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Usage required"},"children":["Usage required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Status of the pairing request — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inProgress"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure"]},". If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inProgress"]},", more responses will follow."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The text message to display to the merchant."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integrationKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The integration key that's returned, to be used to authenticate when transacting."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"response-example","__idx":6},"children":["Response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\"message\": \"Pairing successful\",\n\"status\":\"success\",\n\"integrationKey\":\"***********************\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"demo","__idx":7},"children":["Demo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To learn more about the implementation of headless pairing:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://jsfiddle.net/IntegrationSupport/rq5e4yjL/42/"},"children":["JS Fiddle demo"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]}," if you make changes in the JS Fiddle — click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Run"]}," instead. Clicking Save"," ","may break the fiddle's functionality."]}]}]},"headings":[{"value":"Pairing","id":"pairing","depth":1},{"value":"Embedded API code example","id":"embedded-api-code-example","depth":3},{"value":"Pairing API code (headless pairing) example I","id":"pairing-api-code-headless-pairing-example-i","depth":3},{"value":"Pairing API code (headless pairing) example II","id":"pairing-api-code-headless-pairing-example-ii","depth":3},{"value":"Specification","id":"specification","depth":3},{"value":"Handling the response","id":"handling-the-response","depth":3},{"value":"Response example","id":"response-example","depth":4},{"value":"Demo","id":"demo","depth":3}],"frontmatter":{"title":"Pairing","seo":{"title":"Pairing"}},"lastModified":"2026-09-20T23:33:08.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-person-payments/pay-in-person/integration-guide/js-library/pairing","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}