{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Pay In-Person API","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":"pay-in-person-api","__idx":0},"children":["Pay In-Person API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrate your POS with Tyro Pro payment terminals to process card payments, cashouts, and refunds in person, with real-time transaction status delivered via webhooks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-it","__idx":1},"children":["What is it?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tyro’s Pay In-Person API lets businesses initiate and manage transactions from their own Point of Sale (POS) systems, while Tyro Pro handles the payment interaction at the terminal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your POS creates a Pay Request for the transaction, such as a payment, cashout, or refund, then sends it to the terminal for processing. Real-time updates are delivered to your POS via webhooks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":2},"children":["Requirements"]},{"$$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":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integration type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["In-person (POS/terminal)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhooks"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This API is notified exclusively via webhooks — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/notification-events"},"children":["Webhook events"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Setup steps"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant authorises your POS in the Integration Portal, enables Integrated mode on each Tyro Pro, then pairs it — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/account-authorisation"},"children":["Account authorisation"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Limitations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limited to 1 request per 250ms per merchant/terminal combination — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#conditions-and-limitations"},"children":["Conditions and limitations"]}," below"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API reference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#api-reference"},"children":["Jump to API reference"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-features","__idx":3},"children":["Key features"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operational efficiency"]},": Payment processing happens inside your existing POS, so there's no need to switch systems or re-enter transaction data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Improved customer experience"]},": All payment interactions happen in one unified interface, for faster, smoother service."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reliable status updates"]},": Webhooks notify your backend of every transaction event — such as successful payments or failures — so you always have accurate, timely status."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":4},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The merchant must authorise your POS to integrate with their Tyro account(s) (MIDs) via Tyro's Integration Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Integrated mode must be enabled on each Tyro Pro terminal that will be used."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each terminal must be paired with the POS."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/account-authorisation"},"children":["Account authorisation"]}," for the full walkthrough, including portal screenshots."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":5},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a Pay Request"]}," — Your POS sends the merchant ID, terminal ID, amount, and a unique transaction identifier to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/create-pay-terminal-request"},"children":["Create a pay request"]},", which triggers the terminal to start processing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receive status updates"]}," — The terminal's progress, such as \"waiting for PIN\" or \"completed\", is delivered to your system as ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/notification-events"},"children":["webhook events"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fetch details if needed"]}," — Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/get-pay-terminal-request"},"children":["Retrieve a pay request"]}," for the latest status and full details, such as approval codes and receipts, if a webhook is missed or for reconciliation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respond to prompts or cancel"]}," — Send an answer to a terminal prompt, such as \"Would you like a receipt?\", via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/answer-pay-terminal-prompt"},"children":["Answer a terminal prompt"]},", or cancel the transaction via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/cancel-pay-terminal-request"},"children":["Cancel a pay request"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-sequence","__idx":6},"children":["Example sequence"]},{"$$mdtype":"Tag","name":"p","attributes":{"style":{"textAlign":"center"}},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/pay-terminal-workflow.d6c932519c65cf2dc38707e020d68109fd1f9cbf23d5ff51f369d1ef2aa14298.68286485.png","alt":"Pay in-person sequence"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conditions-and-limitations","__idx":7},"children":["Conditions and limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limiting"]},": Requests are limited to 1 per 250ms per merchant/terminal combination. Exceeding this returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RATE_LIMIT_EXCEEDED"]}," error — bank or debounce requests to avoid it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Terminal availability"]},": A Pay Request may not reach the terminal if it's offline or its network is down. You can safely retry the same Pay Request, unchanged, using the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origin.transactionId"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notifications","__idx":8},"children":["Notifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This API delivers updates exclusively via webhooks, for timely and reliable delivery to your endpoints. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/notification-events"},"children":["Webhook events"]}," for the full list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your system needs notifications through another mechanism, such as websockets, please raise a support request using our new ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tyropayments.atlassian.net/servicedesk/customer/portal/149"},"children":["Integration Support Portal"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-started","__idx":9},"children":["Getting started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/how-to-use"},"children":["How to use"]}," for a detailed walkthrough of creating and managing Pay Requests, including rate limits and edge cases. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/testing"},"children":["Testing"]}," covers simulating terminal responses in sandbox mode without a physical terminal, and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/error-codes"},"children":["Error codes"]}," lists the errors you may need to handle."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-reference","__idx":10},"children":["API reference"]},{"$$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":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/merchants/authorise-pay-terminal-mid-test"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pay-terminal/merchants/{merchantId}/authorise/test"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorise a sandbox merchant ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/merchants/fetch-pay-terminal-merchant"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /pay-terminal/merchants/{merchantId}"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fetch a merchant"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/merchants/list-pay-terminal-merchants"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /pay-terminal/merchants"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lists merchants"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/merchants/list-pay-terminal-merchants-terminals"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /pay-terminal/merchants/{merchantId}/terminals"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lists the terminals available to a merchant"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/answer-pay-terminal-prompt"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /pay-terminal/requests/{payRequestId}"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Answer a terminal prompt"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/cancel-pay-terminal-request"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /pay-terminal/requests/{payRequestId}"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancel a pay request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/create-pay-terminal-request"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pay-terminal/requests"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a pay request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/get-pay-terminal-request"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /pay-terminal/requests/{payRequestId}"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieve a pay request"]}]}]}]}]}]},"headings":[{"value":"Pay In-Person API","id":"pay-in-person-api","depth":1},{"value":"What is it?","id":"what-is-it","depth":2},{"value":"Requirements","id":"requirements","depth":2},{"value":"Key features","id":"key-features","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Example sequence","id":"example-sequence","depth":2},{"value":"Conditions and limitations","id":"conditions-and-limitations","depth":2},{"value":"Notifications","id":"notifications","depth":2},{"value":"Getting started","id":"getting-started","depth":2},{"value":"API reference","id":"api-reference","depth":2}],"frontmatter":{"title":"Overview","seo":{"title":"Pay In-Person API"}},"lastModified":"2026-09-10T06:51:58.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-person-payments/pay-in-person/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}