CINXE.COM
REST API - Connect
<!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1.0"/> <title>REST API - Connect</title> <link rel="apple-touch-icon" sizes="76x76" href="/favicons/apple-touch-icon.png?v=dLJendOlMG"> <link rel="icon" type="image/png" sizes="32x32" href="/favicons/favicon-32x32.png?v=dLJendOlMG"> <link rel="icon" type="image/png" sizes="16x16" href="/favicons/favicon-16x16.png?v=dLJendOlMG"> <link rel="manifest" href="/favicons/site.webmanifest?v=dLJendOlMG"> <link rel="mask-icon" href="/favicons/safari-pinned-tab.svg?v=dLJendOlMG" color="#e60975"> <link rel="shortcut icon" href="/favicons/favicon.ico?v=dLJendOlMG"> <meta name="apple-mobile-web-app-title" content="Paymentsense - Connect"> <meta name="application-name" content="Paymentsense - Connect"> <meta name="msapplication-TileColor" content="#e60975"> <meta name="theme-color" content="#ffffff"> <link href="/lib/swagger-ui/dist/swagger-ui.css" rel='stylesheet' type='text/css' /> <link rel="stylesheet" href="/lib/bootstrap/dist/css/bootstrap.css" /> <link rel="stylesheet" href="/css/site.css?v=od0x-a5VJRY8lWP0uqeC7-jSkMaEc3-QdDKb4sqWCT4" /> <link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet"> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.0/jquery.min.js"></script> </head> <body> <nav class="navbar navbar-fixed-top bg-white"> <div class="container-fluid"> <div class="navbar-header"> <a class="navbar-brand" href="/"> <img class="connect-docs-logo" src="/images/connect_docs_logo.png" alt="Paymentsense"/> </a> <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/"> <img class="paymentsense-logo" src="/images/paymentsense-logo-dark.svg" alt="Paymentsense"/> </a> </div> <div id="navbar" class="navbar-collapse collapse navbar-hide bg-gray-fade"> <ul class="nav nav-pills nav-stacked menu-overview"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Overview</div> </li> <li class="nav-stacked-item"> <a href="/">Introduction</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-rest-interface"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>REST Interface</div> </li> <li class="nav-stacked-item"> <a href="/rest/getting-started">Getting Started</a> </li> <li class="nav-stacked-item"> <a href="/rest/pac-transaction-flow">PAC Transaction Flow</a> </li> <li class="nav-stacked-item"> <a href="/rest/api">API</a> </li> <li class="nav-stacked-item"> <a href="/rest/error-messages">Built-in user messages</a> </li> <li class="nav-stacked-item"> <a href="/rest/changelog">Changelog</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-websockets-interface"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>WebSockets Interface</div> </li> <li class="nav-stacked-item"> <a href="/websockets/getting-started">Getting Started</a> </li> <li class="nav-stacked-item"> <a href="/websockets/pac-transaction-flow">PAC Transaction Flow</a> </li> <li class="nav-stacked-item"> <a href="/websockets/api">API</a> </li> <li class="nav-stacked-item"> <a href="/websockets/changelog">Changelog</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-next-steps"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Next Steps</div> </li> <li class="nav-stacked-item"> <a href="/next-steps/integration-checklist">Integration Checklist</a> </li> <li class="nav-stacked-item"> <a href="/next-steps/qa-process">QA Process</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-help-support"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Help & Support</div> </li> <li class="nav-stacked-item"> <a href="/pdq/test-cards">Test Cards</a> </li> <li class="nav-stacked-item"> <a href="/pdq/invoking-scenarios">Invoking Scenarios</a> </li> <li class="nav-stacked-item"> <a href="/faqs">FAQs</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-ingenico-guides"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Ingenico PDQ Guides</div> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/ict-setup">iCT Setup</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/iwl-setup">iWL Setup</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/internet-connectivity">Checking Internet Connectivity</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/static-ip">Setting a Static IP Address</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/tms-call">Performing a TMS Call</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/pair-base">Pairing an iWL to a base</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/standalone-mode">Switching to Standalone Mode</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/supervisor-password">Changing the Supervisor Password</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/configuration-options">Configuration Options</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-connect-e"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Connect-E</div> </li> <li class="nav-stacked-item"> <a href="/ConnectE/GettingStarted">Getting Started</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/PaymentsFlows">Payment Flows</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/BestPractice">Best Practices</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Standard">Standard - One off Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/RecurringPayment">Standard - Repeat Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/WaitPreExecuteOneOffPayment">Wait Pre-execute - One off Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/WaitPreExecuteRecurringPayment">Wait Pre-execute - Repeat Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/SavePaymentMethodOneOffPayment">Save Payment Method - One off Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Checkout">Checkout</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Wallet">Wallet</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/ApplePay">Apple Pay™</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/GooglePay">Google Pay™</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Webhooks">Webhooks</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/RestApi">REST API</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/SettingUpTestAccount">Setup Test Account</a> </li> </ul> </div> </div> </nav> <div class="box bg-gray-fade"> <div class="flex-row header"> <div class="sidebar side-nav" role="navigation"> <ul class="nav nav-pills nav-stacked menu-overview"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Overview</div> </li> <li class="nav-stacked-item"> <a href="/">Introduction</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-rest-interface"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>REST Interface</div> </li> <li class="nav-stacked-item"> <a href="/rest/getting-started">Getting Started</a> </li> <li class="nav-stacked-item"> <a href="/rest/pac-transaction-flow">PAC Transaction Flow</a> </li> <li class="nav-stacked-item"> <a href="/rest/api">API</a> </li> <li class="nav-stacked-item"> <a href="/rest/error-messages">Built-in user messages</a> </li> <li class="nav-stacked-item"> <a href="/rest/changelog">Changelog</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-websockets-interface"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>WebSockets Interface</div> </li> <li class="nav-stacked-item"> <a href="/websockets/getting-started">Getting Started</a> </li> <li class="nav-stacked-item"> <a href="/websockets/pac-transaction-flow">PAC Transaction Flow</a> </li> <li class="nav-stacked-item"> <a href="/websockets/api">API</a> </li> <li class="nav-stacked-item"> <a href="/websockets/changelog">Changelog</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-next-steps"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Next Steps</div> </li> <li class="nav-stacked-item"> <a href="/next-steps/integration-checklist">Integration Checklist</a> </li> <li class="nav-stacked-item"> <a href="/next-steps/qa-process">QA Process</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-help-support"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Help & Support</div> </li> <li class="nav-stacked-item"> <a href="/pdq/test-cards">Test Cards</a> </li> <li class="nav-stacked-item"> <a href="/pdq/invoking-scenarios">Invoking Scenarios</a> </li> <li class="nav-stacked-item"> <a href="/faqs">FAQs</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-ingenico-guides"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Ingenico PDQ Guides</div> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/ict-setup">iCT Setup</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/iwl-setup">iWL Setup</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/internet-connectivity">Checking Internet Connectivity</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/static-ip">Setting a Static IP Address</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/tms-call">Performing a TMS Call</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/pair-base">Pairing an iWL to a base</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/standalone-mode">Switching to Standalone Mode</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/supervisor-password">Changing the Supervisor Password</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/software-version">Checking the Software Version</a> </li> <li class="nav-stacked-item"> <a href="/pdq/ingenico/configuration-options">Configuration Options</a> </li> </ul> <ul class="nav nav-pills nav-stacked menu-connect-e"> <li class="title"> <span class="collapse-button pull-right glyphicon glyphicon-chevron-down"></span> <div>Connect-E</div> </li> <li class="nav-stacked-item"> <a href="/ConnectE/GettingStarted">Getting Started</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/PaymentsFlows">Payment Flows</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/BestPractice">Best Practices</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Standard">Standard - One off Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/RecurringPayment">Standard - Repeat Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/WaitPreExecuteOneOffPayment">Wait Pre-execute - One off Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/WaitPreExecuteRecurringPayment">Wait Pre-execute - Repeat Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/SavePaymentMethodOneOffPayment">Save Payment Method - One off Payment</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Checkout">Checkout</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Wallet">Wallet</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/ApplePay">Apple Pay™</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/GooglePay">Google Pay™</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/Webhooks">Webhooks</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/RestApi">REST API</a> </li> <li class="nav-stacked-item"> <a href="/ConnectE/SettingUpTestAccount">Setup Test Account</a> </li> </ul> </div> </div> <div class="flex-row content container-fluid main-content"> <div class="page-header"> <h1>REST API <select onclick="" id="version-selector"><option value="v2">v2</option><option value="v1">v1</option><option value="v0">v0</option></select></h1> <p>For versioning see <a href="/rest/getting-started">"API Version Header"</a> and <a href="/rest/changelog">changelog</a>.</p> </div> <div class="separated-text-section first-in-page"> <h2>Interactive Docs</h2> <p>If you've got test credentials for Connect Cloud then this documentation page can be used to interact with our API and any Paymentsense terminal that has been provided to you.</p> <p>To get started:</p> <ol> <li>Enter your test account name. The remainder of the URL generally shouldn't need to be changed.</li> <div class="row swagger-ui-wrap"> <div class="col-sm-6"> <div class="input-group"> <div class="input-group-addon">https://</div> <input type="text" id="rest-account-input" name="rest-account-input" placeholder="your-account" class="form-control request-info" /> <input type="text" id="rest-host-input" name="rest-host-input" placeholder=".test.connect.paymentsense.cloud" class="form-control request-info" /> </div> </div> </div> <br /> <li>Click the 'Authorize' button. Enter any username and place your API key into the password field.</li> <div id="btn-authorize-in-steps"> </div> <br /> <li class="v0-v1-hide">The docs use values of <strong>docsSWH</strong> for the <strong>Software-House-Id</strong> header and <strong>docsInstaller</strong> for the <strong>Installer-Id</strong> header. In your EPoS, the provided values should be used.</li> <li>Use 'Try it out!' on the endpoints to see an end-to-end interaction with the terminal.</li> <li>You can view the expected requests and responses for each endpoint, including example values and detailed models.</li> </ol> <div class="pat-content alert alert-danger" role="alert"> <h4 class="alert-heading">Warning!</h4> <p>If you have found this page by accident, please be aware that we are no longer accepting Pay-At-Table integrations using the REST interface. Please see the WebSockets interface if you would like to continue with a Pay-At-Table integration.</p> </div> <div class="unsupported-version-warning alert alert-danger" role="alert"> <h4 class="alert-heading">Warning!</h4> <p>We are no longer accepting integrations using this API version. Please use the latest API version (v2) if you are integrating for the first time.</p> </div> <div class="new-version-warning alert alert-warning" role="alert"> <h4 class="alert-heading">Warning!</h4> <p>Some features in this API version (e.g. cashback via the API) will not work without an updated terminal software. You can check the version on your PDQ by following the steps <a href="/pdq/ingenico/software-version">here</a>. If this is not x053 or greater (e.g. 9053 or 4054), please contact us.</p> </div> <div class="swagger-section"> <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </div> </div> <div class="separated-text-section"> <h2>Polling Frequency</h2> <h4>Pay-At-Counter</h4> <p> The suggested polling frequency is <strong>1 second</strong>. <br />Anything between 0.5 and 2 seconds is also fine if a different responsiveness/bandwidth/performance tradeoff is preferred. <br />Anything lower that 0.5 is generally unnecessary given the pace of transactions and the frequency of card machine notifications. </p> <p>To avoid missing notifications in-between polling periods, it's suggested to keep track of the already displayed ones and always go through the list of notifications to action any newly received one.</p> <h4 class="pat-content">Pay-At-Table</h4> <p class="pat-content"> The suggested polling frequency is <strong>5 seconds</strong>. <br />Anything between 1 and 30 seconds is also fine since, in this mode, the EPoS mostly acts as a passive observer for payments. </p> </div> <div class="separated-text-section"> <h2>Rate Limiting</h2> <p>Connect may enforce a delay of 0.1 seconds between requests.</p> </div> <div class="separated-text-section"> <h2>Data Availability</h2> <p>Integration data will be available in Connect for a number of hours, so that the EPoS has time to retrieve it.</p> <p>However, we recommend that you get this information as soon as possible from Connect and only rely on its presence in our cloud in case of failures (network drops, data loss, crashes, etc).</p> <h4>Pay-At-Counter</h4> <p>Transactions and reports requested to card machines can be retrieved for 12 hours from their completion.</p> <h4 class="pat-content">Pay-At-Table</h4> <p class="pat-content">Table data can be retrieved until a table is explicitly removed from Connect.</p> <p class="pat-content">End of Day reports that PDQs have sent to the REST interface are available for 7 days.</p> </div> <h2>Next Steps</h2> <p>Once you've completed the integration, use the <a href="/next-steps/integration-checklist">Checklist</a> to ensure that everything has been implemented as expected.</p> </div> </div> <script src="/lib/jquery/dist/jquery.js"></script> <script src="/lib/bootstrap/dist/js/bootstrap.js"></script> <script src="/js/site.js?v=EJoUa2zJf1jD2gOSD-bFxcqjh7BTi3T8Syelg9L4Zs4"></script> <script> (function(i, s, o, g, r, a, m) { i['GoogleAnalyticsObject'] = r; i[r] = i[r] || function() { (i[r].q = i[r].q || []).push(arguments) }, i[r].l = 1 * new Date(); a = s.createElement(o), m = s.getElementsByTagName(o)[0]; a.async = 1; a.src = g; m.parentNode.insertBefore(a, m) })(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga'); ga('create', 'UA-102643555-1', 'auto'); ga('send', 'pageview'); </script> <script src="/lib/swagger-ui/dist/swagger-ui-bundle.js"></script> <script src="/lib/swagger-ui/dist/swagger-ui-standalone-preset.js"></script> <script type="text/javascript"> $(function () { let url = "/js/swagger_v2.json"; let host = window.location.search.match(/host=([^&]+)/); let accountName = "your-account"; let hostEnding = ".test.connect.paymentsense.cloud"; let spec; let version = "v2"; let SWHId = "docsSWH"; let IId = "docsInstaller"; $('.unsupported-version-warning').hide(); if (host && url.length > 1) { host = decodeURIComponent(host[1]); } else { host = "your-account.test.connect.paymentsense.cloud"; } // Pre load translate... if (window.SwaggerTranslator) { window.SwaggerTranslator.translate(); } $.getJSON(url, function (data) { spec = data; initSwagger($("#version-selector").val()); }); $('#version-selector').change(function () { version = $("#version-selector").val(); url = '/js/swagger_' + version + '.json'; $.getJSON(url, function (data) { spec = data; $('.btn.authorize').remove(); initSwagger(); }); if (version == "v0" || version == "v1") { $('.v0-v1-hide').hide(); $('.new-version-warning').hide(); $('.unsupported-version-warning').show(); } else { $('.v0-v1-hide').show(); $('.new-version-warning').show(); $('.unsupported-version-warning').hide(); }; }); function log() { if ('console' in window) { console.log.apply(console, arguments); } } $('#rest-account-input').blur(function () { accountName = $("#rest-account-input").val() if (accountName === "") { accountName = "your-account"; }; host = accountName + hostEnding; $('.btn.authorize').remove(); initSwagger(); }); $('#rest-host-input').blur(function () { hostEnding = $("#rest-host-input").val(); if (hostEnding === "") { hostEnding = ".test.connect.paymentsense.cloud"; }; host = accountName + hostEnding; $('.btn.authorize').remove(); initSwagger(); }); function initSwagger() { if (version == "v0" || version == "v1") { spec.host = host; } else { spec.servers[0].url = "https://" + host; }; spec.url = url; ui = SwaggerUIBundle({ url: url, spec: spec, dom_id: '#swagger-ui-container', presets: [ SwaggerUIBundle.presets.apis, // yay ES6 modules Array.isArray(SwaggerUIStandalonePreset) ? SwaggerUIStandalonePreset : SwaggerUIStandalonePreset.default ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout", onComplete: function (swaggerApi, swaggerUi) { if (window.SwaggerTranslator) { window.SwaggerTranslator.translate(); } $('.btn.authorize').addClass('btn').addClass('btn-success'); var authorizeElement = $('.btn.authorize').detach(); $('#btn-authorize-in-steps').append(authorizeElement); resolvePatElements(); }, docExpansion: "none", onFailure: function (data) { log("Unable to Load SwaggerUI"); }, jsonEditor: false, defaultModelRendering: 'schema', showRequestHeaders: true, showOperationIds: false, requestInterceptor: (req) => { if (!req.loadSpec && version != "v0" && version != "v1") { req.headers.set req.headers["Software-House-Id"] = SWHId; req.headers["Installer-Id"] = IId; } return req; }, }) window.ui = ui } function getUrlVars() { var vars = [], hash; var hashes = window.location.href.slice(window.location.href.indexOf('?') + 1).split('&'); for (var i = 0; i < hashes.length; i++) { hash = hashes[i].split('='); vars.push(hash[0]); vars[hash[0]] = hash[1]; } return vars; }; function resolvePatElements() { var queryStringParams = getUrlVars(); var patEnabled = queryStringParams["withPat"]; if (patEnabled === undefined || patEnabled != 1) { $('#operations-tag-PAT_Tables').hide(); $('#operations-tag-PAT_Reports').hide(); $('#operations-tag-Hospitality_Tables').hide(); $('#operations-tag-Hospitality_Reports').hide(); } else { $('.pat-content').show(); } } }); </script> </body> </html>