{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"POS / Terminal Integration","siteUrl":"https://developer.flute.com","description":"Documentation and API reference for integrating Flute payment processing.","lang":"en-US","llmstxt":{"hide":true,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"pos--terminal-integration","__idx":0},"children":["POS / Terminal Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flute provides a semi-integrated POS solution where your point-of-sale system sends transaction requests to the Flute API, which routes them to a physical terminal for card processing. The terminal handles all card interaction (tap, insert, swipe) and communicates the result back through the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How It Works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your POS system creates a transaction via the API, specifying the terminal and amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Flute sends the transaction to the terminal via push notification."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The terminal prompts the customer to present their card."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The terminal processes the payment and reports the result."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your POS system retrieves the result by polling the API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"base-url","__idx":2},"children":["Base URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox Environment:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://sandbox.api.flute.com/pos-api/v1\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production Environment:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api.flute.com/pos-api/v1\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"terminals","__idx":3},"children":["Terminals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before processing transactions, you need to know which terminals are available."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-terminals","__idx":4},"children":["List Terminals"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /pos-api/v1/terminals\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns a paginated list of terminals assigned to your merchant account."]},{"$$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":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Items per page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["search"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search by terminal name or serial number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["serialNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by serial number."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each terminal in the response includes:"]},{"$$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":"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":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Terminal unique identifier. Use this when creating transactions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["serialNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The terminal's hardware serial number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["terminalManufacturer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manufacturer name, such as Sunmi, Verifone."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["terminalModel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Model name, such as P2, P3H, Victa Mobile."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["terminalModeName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operating mode (Standalone or SemiIntegrated)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["connectionStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Current connection state (Online or Offline)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-terminal-status","__idx":5},"children":["Get Terminal Status"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /pos-api/v1/terminals/{terminalId}/status\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns detailed real-time status for a specific terminal, including connectivity, battery level, and printer status."]},{"$$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":"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":["terminalPosStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Active (ready to accept transactions) or Busy (currently processing)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["connectionStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Online or Offline."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["connectionType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WiFi, Mobile, or Ethernet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["batteryLevel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Battery percentage (0–100)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["printerStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Normal, NotNormal, or NotSupported."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["availabilityStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ready or Busy."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that a terminal is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Online"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Active"]}," before sending a transaction to avoid a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TerminalOffline"]}," status."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-transaction","__idx":6},"children":["Creating a Transaction"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"start-a-pos-transaction","__idx":7},"children":["Start a POS Transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /pos-api/v1/pos-transactions\n"},"children":[]},{"$$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":"Required"},"children":["Required"]},{"$$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":["terminalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The terminal that will process the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["transactionTypeId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction type (see table below)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["decimal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount in dollars. Required for Sale, Authorization, Capture, Refund, and Tip Adjustment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["posDeviceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your POS system's device identifier (max 36 characters)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["referenceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your external reference ID for this transaction (max 36 characters)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["targetTransactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The original transaction ID. Required for Void, Capture, and Refund."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["customerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Associate the transaction with a stored customer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["readingMethodId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1 = Card read (tap/insert/swipe, default), 2 = Manual entry (keyed)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["waitForAcceptanceByTerminal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["bool"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["true = long poll until terminal accepts; false = return immediately (default)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-types","__idx":8},"children":["Transaction Types"]},{"$$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":"ID"},"children":["ID"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$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":["1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Place a hold on funds without capturing. Requires amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sale"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorize and capture in one step. Requires amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capture"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capture a previous authorization. Requires amount and targetTransactionId."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["4"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Void"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancel a transaction before settlement. Requires targetTransactionId."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["5"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refund"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return funds from a settled transaction. Requires amount and targetTransactionId."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["8"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tip Adjustment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Adjust the tip on an existing transaction. Requires amount and targetTransactionId."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example — Sale transaction:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://sandbox.api.flute.com/pos-api/v1/pos-transactions' \\\n  -H 'Authorization: Bearer API_TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"terminalId\": \"d4e5f6a7-b8c9-0123-4567-89abcdef0123\",\n    \"transactionTypeId\": 2,\n    \"amount\": 25.99,\n    \"posDeviceId\": \"POS-REGISTER-01\",\n    \"referenceId\": \"ORDER-4521\",\n    \"waitForAcceptanceByTerminal\": false\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"posTransactionId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"statusId\": 1,\n  \"status\": \"TerminalConnecting\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-pos-transaction","__idx":9},"children":["Get POS Transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /pos-api/v1/pos-transactions/{posTransactionId}\n"},"children":[]},{"$$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":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["posTransactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path parameter. The POS transaction ID returned from the create call."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["waitForTransactionProcessing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["bool"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Query parameter. Set to true for long polling — the response holds until the transaction completes or times out."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the transaction completes (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isCompleted: true"]},"), the response includes full transaction details in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction"]}," object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"posTransactionStatusId\": 6,\n  \"posTransactionStatus\": \"Completed\",\n  \"isCompleted\": true,\n  \"amount\": 25.99,\n  \"transaction\": {\n    \"transactionId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n    \"amount\": 25.99,\n    \"transactionStatus\": \"Captured\",\n    \"authCode\": \"A12345\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"polling-for-results","__idx":10},"children":["Polling for Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After creating a transaction, poll the GET endpoint to track its progress."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"polling-strategies","__idx":11},"children":["Polling Strategies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Polling when creating a transaction:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Short polling:"]}," Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waitForAcceptanceByTerminal: false"]}," when creating the POS transaction. Your POS controls the polling interval to retrieve the transaction status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Long polling:"]}," Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waitForAcceptanceByTerminal: true"]}," when creating the POS transaction. The response holds until the transaction is accepted by the terminal device or times out, reducing the number of API calls."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Polling to get the transaction results:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Short polling:"]}," Poll GET with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waitForTransactionProcessing: false"]}," when you want to check the transaction status at your own interval."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Long polling:"]}," Poll GET with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waitForTransactionProcessing: true"]}," to hold the request until the transaction reaches a final status, reducing the number of API calls."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-status-lifecycle","__idx":12},"children":["Transaction Status Lifecycle"]},{"$$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":"ID"},"children":["ID"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Final?"},"children":["Final?"]},{"$$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":["1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TerminalConnecting"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction sent to the terminal. Waiting for the terminal to accept."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TransactionProcessing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Terminal accepted the transaction and is processing the card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["10"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TransactionSentToProcessor"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card data submitted to the payment processor."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["6"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Completed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction processed successfully."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DeclinedByProcessor"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payment processor declined the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["4"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CancelByPos"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your POS system cancelled the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["5"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CancelByTerminal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction was cancelled at the terminal (e.g. customer pressed cancel)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["9"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TerminalOffline"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The terminal could not be reached."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["7"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A system error occurred during processing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["8"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inconsistency"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A data mismatch occurred between the POS and terminal."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isCompleted"]}," field to determine if the transaction has reached a final status."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancelling-a-transaction","__idx":13},"children":["Cancelling a Transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can cancel a transaction that hasn't completed yet."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /pos-api/v1/pos-transactions/{posTransactionId}/cancel\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns the updated transaction status. Cancellation is only possible while the transaction is in a non-final state (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TerminalConnecting"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionProcessing"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listing-transactions","__idx":14},"children":["Listing Transactions"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /pos-api/v1/pos-transactions\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns a paginated list of POS transactions. Supports filtering by terminal."]},{"$$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":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Items per page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["terminalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter transactions by terminal."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["bool"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sort order. true = ascending, false = descending."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["orderBy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field name to sort by."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"printing-a-receipt","__idx":15},"children":["Printing a Receipt"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trigger a receipt reprint on a terminal for a completed transaction."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /pos-api/v1/pos-transactions/{posTransactionId}/print\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"terminalId\": \"d4e5f6a7-b8c9-0123-4567-89abcdef0123\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," with no body. The specified terminal will print the receipt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-responses","__idx":16},"children":["Error Responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All endpoints return standard HTTP error codes:"]},{"$$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":"Status Code"},"children":["Status Code"]},{"$$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":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid request — check that required fields are present and correctly formatted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["401 Unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid API token."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["403 Forbidden"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your account does not have the required POS permission."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The specified transaction or terminal was not found."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500 Internal Server Error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unexpected error occurred. Contact support if the issue persists."]}]}]}]}]}]},"headings":[{"value":"POS / Terminal Integration","id":"pos--terminal-integration","depth":1},{"value":"How It Works","id":"how-it-works","depth":2},{"value":"Base URL","id":"base-url","depth":2},{"value":"Terminals","id":"terminals","depth":2},{"value":"List Terminals","id":"list-terminals","depth":3},{"value":"Get Terminal Status","id":"get-terminal-status","depth":3},{"value":"Creating a Transaction","id":"creating-a-transaction","depth":2},{"value":"Start a POS Transaction","id":"start-a-pos-transaction","depth":3},{"value":"Transaction Types","id":"transaction-types","depth":3},{"value":"Get POS Transaction","id":"get-pos-transaction","depth":2},{"value":"Polling for Results","id":"polling-for-results","depth":2},{"value":"Polling Strategies","id":"polling-strategies","depth":3},{"value":"Transaction Status Lifecycle","id":"transaction-status-lifecycle","depth":2},{"value":"Cancelling a Transaction","id":"cancelling-a-transaction","depth":2},{"value":"Listing Transactions","id":"listing-transactions","depth":2},{"value":"Printing a Receipt","id":"printing-a-receipt","depth":2},{"value":"Error Responses","id":"error-responses","depth":2}],"frontmatter":{"title":"POS / Terminal Integration","description":"Integrate your POS system with Flute terminals to accept in-person card payments using the semi-integrated model.","seo":{"title":"POS / Terminal Integration"}},"lastModified":"2026-06-04T22:05:58.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-person-payments/pos-terminal-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}