# JSON-RPC API Reference This document describes the JSON-RPC API methods supported by the Teya Unified EPOS SDK. ## Table of Contents **Methods** - [initialize](#initialize) - [setup](#setup) - [setupAuthAndStore](#setupauthandstore) - [getTerminals](#getterminals) - [linkTerminal](#linkterminal) - [clearDeviceLink](#cleardevicelink) - [clearUserAuth](#clearuserauth) - [makePaymentAndSubscribe](#makepaymentandsubscribe) - [unsubscribeAll](#unsubscribeall) - [cancelPayment](#cancelpayment) - [refundPayment](#refundpayment) - [makeUnreferencedRefund](#makeunreferencedrefund) - [printCustomTemplate](#printcustomtemplate) - [printCustomImage](#printcustomimage) - [zipLogs](#ziplogs) - [openTab](#opentab) - [listTabs](#listtabs) - [getTab](#gettab) - [closeTab](#closetab) - [respondToBillRequest](#respondtobillrequest) - [respondWithError](#respondwitherror) - [subscribeTabEvents](#subscribetabevents) - [unsubscribeTabEvents](#unsubscribetabevents) - [setPayAtTableEnabledOnStore](#setpayattableenabledonstore) **Common Definitions** - [General](#pkg-com-teya-unifiedepssdk-rpcmodels) - [Payments](#pkg-com-teya-unifiedepssdk-rpcmodels-payments) - [Printing](#pkg-com-teya-unifiedepssdk-rpcmodels-printing) - [Setup](#pkg-com-teya-unifiedepssdk-rpcmodels-setup) - [Tabs](#pkg-com-teya-unifiedepssdk-rpcmodels-tabs) ## initialize Initializes the PosLink integration. PosLink is a Teya Cloud service designed to handle payment requests and deliver push notifications to the terminal linked by the user during the "setup" method call. During the first successful "setup" method call, the user will also be required to log in to their Teya account. ### Request ```json { "jsonrpc": "2.0", "method": "initialize", "params": { "requesterId": "com.company.eposapp", "requesterVersion": "1.0.0", "isProductionEnv": true, "clientId": "", "clientSecret": "", "eposInstanceId": "-", "initialUserAccessToken": "" }, "id": "30db5978-22c6-306c-a737-052260426f45" } ``` - **[Parameters](#initialize-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `requesterId` | `String` | Yes | ePOS Application identifier. | | `requesterVersion` | `String` | Yes | ePOS Application version. | | `isProductionEnv` | `Boolean` | Yes | SDK will use production endpoints if true, otherwise it will use dev endpoints. | | `clientId` | `String` | Yes | client id associated with the environment set by `isProductionEnv`. | | `clientSecret` | `String` | Yes | client secret associated with the environment set by `isProductionEnv`. | | `eposInstanceId` | `String` | No | A unique identifier for the ePOS instance, included in new payment requests sent to the PosLink service. | | `initialUserAccessToken` | `String` | No | An initial user access token the SDK can use to skip the authentication flow UI. Instead, it will try to use this once and migrate to internal credentials. After passing in this token, if you get a successful setup, you can clean it up. If this token is not valid, the SDK will fall back to showing authentication flow UI. This is helpful when migrating from a solution where you managed authentication and want to now rely on the SDK to do so, without asking the user to login again. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "initialize->ack", "integrationsAppVersion": "1.1.0", "integrations_app_version": "1.1.0" }, "id": "30db5978-22c6-306c-a737-052260426f45" } ``` - **[Parameters](#initialize-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `integrationsAppVersion` | `String` | Yes | version of the Teya SDK app. | | `integrations_app_version` | `String` | Yes | Legacy duplicate of `integrationsAppVersion` under the snake_case key `integrations_app_version`, kept for backwards compatibility. New integrations should read `integrationsAppVersion`; this key will be removed in v2. | ## setup Sets up the PosLink integration. If there's no device linked info or no authentication saved in the SDK, it will show Teya UI to help the user authenticate to their Teya account and/or link to their Teya payment device. If no device is linked or authentication data is missing, the SDK will display the Teya UI to guide the user through authentication and device linking. This process typically occurs only during the initial setup or after invoking `clearDeviceLink` or `clearUserAuth`. In such cases, the UI will prompt the user to complete the necessary steps. ### Request ```json { "jsonrpc": "2.0", "method": "setup", "id": "a0f84894-2ce8-33cf-93c0-fa6cc684007d" } ``` ### Response ```json { "jsonrpc": "2.0", "result": { "type": "setup->onResponse", "response": "SUCCESS", "debugErrorMessage": "Invalid client", "store": { "id": "store-id", "name": "My store", "address": { "city": "London", "country": "United Kingdom", "streetAddressLine1": "123 High Street", "streetAddressLine2": "Floor 2", "zipcode": "EC1A 1BB" } }, "terminal": { "id": "terminal-123", "name": "Terminal 1", "serialNumber": "SN123456789" } }, "id": "a0f84894-2ce8-33cf-93c0-fa6cc684007d" } ``` - **[Parameters](#setup-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `response` | `String` (enum: `Response`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setupresult-response) | Yes | `Response` setup result. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | | `store` | `object` (class: `Store`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-store) | No | `Store` store to which the epos is linked to. Present always in cases of "SUCCESS". | | `terminal` | `object` (class: `Terminal`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-terminal) | No | `Terminal` terminal to which the epos is linked to. Present always in cases of "SUCCESS". | - **[`Response` enum values (used on `response`)](#setup-response-response)** `Response` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setupresult-response). - **[`Store` class parameters (used on `store`)](#setup-response-store)** `Store` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-store). - **[`Terminal` class parameters (used on `terminal`)](#setup-response-terminal)** `Terminal` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-terminal). ## setupAuthAndStore Like "setup" method but skips terminal selection step. That step should still be done by using "linkTerminal" method before calling any method that requires a linked terminal. ### Request ```json { "jsonrpc": "2.0", "method": "setupAuthAndStore", "id": "ec82c29e-5726-3d8a-9f19-59b5e7e19fd6" } ``` ### Response Like "setup->onResponse" but will not include the terminal info on successful setup, since that step is skipped for "setupAuthAndStore" method. ```json { "jsonrpc": "2.0", "result": { "type": "setupAuthAndStore->onResponse", "response": "SUCCESS", "debugErrorMessage": "Invalid client", "store": { "id": "store-id", "name": "My store", "address": { "city": "London", "country": "United Kingdom", "streetAddressLine1": "123 High Street", "streetAddressLine2": "Floor 2", "zipcode": "EC1A 1BB" } } }, "id": "ec82c29e-5726-3d8a-9f19-59b5e7e19fd6" } ``` - **[Parameters](#setupauthandstore-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `response` | `String` (enum: `Response`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setupresult-response) | Yes | `Response` setup result. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | | `store` | `object` (class: `Store`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-store) | No | `Store` store to which the epos is linked to. Present always in cases of "SUCCESS". | - **[`Response` enum values (used on `response`)](#setupauthandstore-response-response)** `Response` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setupresult-response). - **[`Store` class parameters (used on `store`)](#setupauthandstore-response-store)** `Store` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-store). ## getTerminals Retrieves the list of terminals associated with the currently linked store. ### Request ```json { "jsonrpc": "2.0", "method": "getTerminals", "params": { "forceRefresh": true }, "id": "4d23d20b-c80a-3bf2-8d45-c18cd2387c27" } ``` - **[Parameters](#getterminals-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `forceRefresh` | `Boolean` | Yes | If true, bypasses the cache and fetches terminals from the network. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "getTerminals->onResult", "terminals": [ { "id": "terminal-123", "name": "Terminal 1", "serialNumber": "SN123456789" } ], "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout has expired" }, "id": "4d23d20b-c80a-3bf2-8d45-c18cd2387c27" } ``` - **[Parameters](#getterminals-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `terminals` | `array of objects` (class: `Terminal`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-terminal) | No | The list of terminals associated with the linked store. Null if the request failed. | | `failureReason` | `String` (enum: `FailureReason`) | No | The reason for the failure, null if the request was successful. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | - **[`Terminal` class parameters (used on `terminals`)](#getterminals-response-terminals)** `Terminal` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-terminal). - **[`FailureReason` enum values (used on `failureReason`)](#getterminals-response-failurereason)** | Name | Description | |------|-------------| | `SETUP_NOT_COMPLETED` | The SDK has not been successfully set up. Call `setup` first. | | `NETWORK_ERROR` | A network error occurred when communicating with the server. | | `OTHER` | An unexpected error occurred, check `debugErrorMessage` for details. | ## linkTerminal Links to a terminal from the current store with the given `terminalId`, or shows the terminal selection UI if `terminalId` is null. ### Request ```json { "jsonrpc": "2.0", "method": "linkTerminal", "params": { "terminalId": "terminal-id" }, "id": "46c830d1-2a55-34f3-a4d9-3bc93be6ab61" } ``` - **[Parameters](#linkterminal-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `terminalId` | `String` | No | Optional ID of the terminal to link. If null, the Teya terminal selection UI is shown. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "linkTerminal->onResult", "terminal": { "id": "terminal-123", "name": "Terminal 1", "serialNumber": "SN123456789" }, "failureReason": "INVALID_TERMINAL_ID", "debugErrorMessage": "Internal server error" }, "id": "46c830d1-2a55-34f3-a4d9-3bc93be6ab61" } ``` - **[Parameters](#linkterminal-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `terminal` | `object` (class: `Terminal`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-terminal) | No | The terminal that was successfully linked | | `failureReason` | `String` (enum: `FailureReason`) | No | The reason for the failure, null if the request was successful. | | `debugErrorMessage` | `String` | No | A debug message that can be used to help debug the issue. | - **[`Terminal` class parameters (used on `terminal`)](#linkterminal-response-terminal)** `Terminal` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-setup-terminal). - **[`FailureReason` enum values (used on `failureReason`)](#linkterminal-response-failurereason)** | Name | Description | |------|-------------| | `SETUP_NOT_COMPLETED` | The SDK has not been successfully set up. Call `setup` first. | | `USER_CANCELED` | The user canceled the terminal linking process. | | `INVALID_TERMINAL_ID` | The provided terminal ID is invalid or does not belong to the currently linked store. | | `NETWORK_ERROR` | A network error occurred when communicating with the server. | | `OTHER` | An unexpected error occurred, check `debugErrorMessage` for details. | ## clearDeviceLink Removes the linked device information. To link a new device, `setup` must be called again. ### Request ```json { "jsonrpc": "2.0", "method": "clearDeviceLink", "id": "fec6c8fe-181b-3988-a101-438909e17d09" } ``` ### Response ```json { "jsonrpc": "2.0", "result": { "type": "clearDeviceLink->ack" }, "id": "fec6c8fe-181b-3988-a101-438909e17d09" } ``` ## clearUserAuth Removes the stored authentication information. To authenticate, `setup` must be called again. ### Request ```json { "jsonrpc": "2.0", "method": "clearUserAuth", "id": "ef0c42f6-b60e-3850-89ac-d24e7b3c5517" } ``` ### Response ```json { "jsonrpc": "2.0", "result": { "type": "clearUserAuth->ack" }, "id": "ef0c42f6-b60e-3850-89ac-d24e7b3c5517" } ``` ## makePaymentAndSubscribe Initiates a communication with the Payment app to make a payment. TIP NOTE: If you provide a tip, it will be included in the total `amount` you pass. The `tip` is not added on top of `amount`, it is part of it. For example: ``` amount = 100 tip = 20 ``` In this case: - The total payment is £1.00 (100 in minor units). - £0.20 (20 in minor units) is considered the tip. NOTES: - `transactionId` should be unique to the store the user is linked to. Meaning, for a given store id, there should not be two transaction ids with the same value. ### Request ```json { "jsonrpc": "2.0", "method": "makePaymentAndSubscribe", "params": { "transactionId": "my-transaction-unique-id", "amount": 420, "currency": "GBP", "useTeyaDefaultUi": true, "tip": 99, "purchaseData": { "lineItems": [ { "product": { "name": "Apple", "description": "a description", "externalProductId": "SKU-31241", "category": "food", "unit": "pcs", "unitGrossPrice": 120, "unitNetPrice": 100, "taxRate": 2050, "taxType": "Vat", "taxCode": "VAT_STANDARD" }, "purchaseLineType": "Product", "quantity": 2, "lineDiscountAmount": 100, "lineTaxAmount": 40, "lineTotalAmount": 200 } ], "discountItems": [ { "code": "DISC1234", "description": "a description", "amount": 100 } ] }, "tabContext": { "tabId": "ORDER-2026-001", "terminalId": "term-001", "type": "FULL", "method": "CARD" } }, "id": "963a1259-6157-367d-a082-e88d8cd1229e" } ``` - **[Parameters](#makepaymentandsubscribe-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transactionId` | `String` | Yes | ePOS unique identifier for this new payment. | | `amount` | `Int` | Yes | The total amount to be paid, including tip, in the smallest unit of the currency (e.g., cents). | | `currency` | `String` | Yes | The ISO 4217 currency code (e.g., "GBP", "EUR"). | | `useTeyaDefaultUi` | `Boolean` | Yes | If true, the SDK will show a Teya default UI for in progress states and interaction. | | `tip` | `Int` | No | An optional tip amount, in the smallest unit of the currency. Denotes of the total `amount` how much the tip was, it will not change the charged amount. | | `purchaseData` | `object` (class: `PurchaseData`) | No | Represents the details of a purchase, including line items and discounts. | | `tabContext` | `object` (class: `TabContext`) | No | Tab context for a payment initiated in response to a `subscribeTabEvents->onPayRequested` event. Set this when settling a tab (fully or partially); leave null for regular payments. | - **[`PurchaseData` class parameters (used on `purchaseData`)](#makepaymentandsubscribe-request-purchasedata)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lineItems` | `array of objects` (class: `LineItem`) | Yes | A list of line items representing the items in the purchase. | | `discountItems` | `array of objects` (class: `DiscountItem`) | Yes | A list of discount items representing the discounts applied to the purchase. | - **[`LineItem` class parameters (used on `lineItems`)](#makepaymentandsubscribe-request-purchasedata-lineitems)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `product` | `object` (class: `Product`) | Yes | Details of the product associated with this line item. | | `purchaseLineType` | `String` (enum: `PurchaseLineType`) | Yes | Type of the item. | | `quantity` | `Double` | Yes | Quantity of the item. | | `lineDiscountAmount` | `Int` | Yes | Total discount amount (not a percentage) for the line, in the smallest currency unit (e.g., 100 pence = £1). | | `lineTaxAmount` | `Int` | No | Total tax amount for the line, in the smallest currency unit. e.g., 2 Oranges with a £0.20 tax each → lineTaxAmount = 40. | | `lineTotalAmount` | `Int` | Yes | Total amount for the line in the smallest currency unit. e.g., 2 Oranges at £1.20 each with a £0.40 line discount → lineTotalAmount = 200. | - **[`Product` class parameters (used on `product`)](#makepaymentandsubscribe-request-purchasedata-lineitems-product)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | `String` | Yes | Name of the item. | | `description` | `String` | No | Optional description of the item. | | `externalProductId` | `String` | Yes | External identifier for the product (e.g., from the partner's system). | | `category` | `String` | Yes | Optional category of the item. | | `unit` | `String` | No | Unit of measurement (e.g., pcs, kg). | | `unitGrossPrice` | `Int` | Yes | Full price charged to the customer for a single unit, including taxes but excluding discounts, in the smallest currency unit (e.g., 100 pence = £1). e.g., Orange costs £1.20 including tax → unitGrossPrice = 120. | | `unitNetPrice` | `Int` | No | Price earned by the merchant for a single unit, excluding taxes and discounts, in the smallest currency unit. e.g., Orange costs £1.20 including tax, tax is £0.20 → unitNetPrice = 100. | | `taxRate` | `Int` | No | Tax rate in **basis points**, where 100 basis points = 1%. | | `taxType` | `String` (enum: `TaxType`) | No | Tax type classification. "Vat" or "VatExempt". | | `taxCode` | `String` | No | Tax code (e.g. `VAT_STANDARD`, `VAT_REDUCED`). | - **[`TaxType` enum values (used on `taxType`)](#makepaymentandsubscribe-request-purchasedata-lineitems-product-taxtype)** | Name | |------| | `Vat` | | `VatExempt` | - **[`PurchaseLineType` enum values (used on `purchaseLineType`)](#makepaymentandsubscribe-request-purchasedata-lineitems-purchaselinetype)** | Name | |------| | `Product` | | `Service` | | `Digital` | | `Tip` | | `Adjustment` | | `Shipping` | - **[`DiscountItem` class parameters (used on `discountItems`)](#makepaymentandsubscribe-request-purchasedata-discountitems)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `code` | `String` | No | Optional discount's code. | | `description` | `String` | No | Optional discount's description. | | `amount` | `Int` | Yes | The discount's amount (not a percentage) in the smallest currency unit (e.g., 100 pence to charge £1). | - **[`TabContext` class parameters (used on `tabContext`)](#makepaymentandsubscribe-request-tabcontext)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided identifier of the tab being paid. | | `terminalId` | `String` | Yes | The terminal that initiated the payment. | | `type` | `String` (enum: `TabPaymentType`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymenttype) | Yes | Whether the payment covers the full outstanding amount or a split portion. | | `method` | `String` (enum: `TabPaymentMethod`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymentmethod) | Yes | How the customer is paying. | - **[`TabPaymentType` enum values (used on `type`)](#makepaymentandsubscribe-request-tabcontext-type)** `TabPaymentType` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymenttype). - **[`TabPaymentMethod` enum values (used on `method`)](#makepaymentandsubscribe-request-tabcontext-method)** `TabPaymentMethod` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymentmethod). ### Response This Response is _streamed_, meaning you will get multiple of these over time for a single `makePaymentAndSubscribe` call. However, only the final one will include the "id" in the json-rpc object. Others can be matched via `transactionId`. Represents a payment state change event during a payment and subscription operation. This class provides details about the state of the payment transaction, its associated metadata, and the reasons for the state, if applicable. ```json { "jsonrpc": "2.0", "result": { "type": "makePaymentAndSubscribe->onPaymentStateChanged", "transactionId": "tx-123", "amount": 1000, "tip": 200, "currency": "GBP", "gatewayPaymentId": "payment-123", "state": "SUCCESSFUL", "inProgressState": "WAITING_FOR_CARD_ENTRY", "isFinal": true, "reason": "CANCELED_BY_USER", "metadata": { "card": { "last4": "1234", "issuingCountry": "GB", "brand": "VISA", "type": "DEBIT" }, "entryMode": "EMV_CONTACTLESS", "verificationMethod": "ONLINE_PIN", "applicationId": "A0000000012345", "merchantAcquiringId": "MID12345", "responseCode": "00", "authorisationCode": "123ABC", "dcc": { "conversionFee": "2.5%", "disclaimer": "I accept to pay in GBP", "exchangeRate": "0.8650", "transactionAmount": 8500, "transactionCurrency": "GBP" } }, "transactionTimestamp": 1733241600000, "debugErrorMessage": "Invalid request" }, "id": "963a1259-6157-367d-a082-e88d8cd1229e" } ``` - **[Parameters](#makepaymentandsubscribe-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transactionId` | `String` | Yes | The ePOS id passed in the `makePaymentAndSubscribe` call. | | `amount` | `Int` | Yes | The final total amount that was charged in minor units. In final successful states, it can be different from the requested one, only if a tip was added in the Payments app. | | `tip` | `Int` | No | The final tip amount in minor units. In final successful states, it can be different from the requested one, only if a tip was added in the Payments app. | | `currency` | `String` | Yes | The currency of the `tip` and `amount`. | | `gatewayPaymentId` | `String` | No | Teya backend id for the payment created. This field will not be null for on "SUCCESSFUL" state. | | `state` | `String` (enum: `PaymentState`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-paymentstate) | Yes | The current state of the payment, see `PaymentState`. | | `inProgressState` | `String` (enum: `InProgressState`) | No | The detailed state of the payment when in `IN_PROGRESS` state, see `InProgressState`. | | `isFinal` | `Boolean` | Yes | Indicates whether the current state of the payment transaction is final. | | `reason` | `String` (enum: `PaymentStateReason`) | No | The reason for the current payment state, if applicable. See `PaymentStateReason`. | | `metadata` | `object` (class: `Metadata`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata) | No | Additional metadata related to the payment, such as card details or response codes. Useful to prepare a consolidated receipt on ePOS side. Available if payment finished successfully. | | `transactionTimestamp` | `Long` | No | The timestamp (in milliseconds since epoch) when the transaction occurred. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | - **[`PaymentState` enum values (used on `state`)](#makepaymentandsubscribe-response-state)** `PaymentState` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-paymentstate). - **[`InProgressState` enum values (used on `inProgressState`)](#makepaymentandsubscribe-response-inprogressstate)** | Name | Description | |------|-------------| | `SENT_TO_PAYMENT_APP` | The payment details have been sent to the Teya payment app. | | `RECEIVED` | The payment details have been successfully received by the payment app. | | `WAITING_FOR_CARD_ENTRY` | Waiting for the customer to start card entry (insert, swipe, or tap). | | `TIP_SELECTION` | Awaiting the customer's interaction regarding tipping. | | `CARD_PRESENTED` | The payment app detected that a card has been presented by the customer. | | `PIN_ENTRY` | The customer is required to enter their PIN. This typically follows card presentation when PIN is required. | | `INSERT_CARD` | The customer is required to insert their card to proceed. | | `DCC_SELECTION` | Waiting for the customer's selection regarding Dynamic Currency Conversion (DCC). | | `REMOVE_CARD` | The customer is required to remove their card from the device. | | `APP_SELECTION` | The customer is selecting a card application on the device. | | `MOTO_FORM_SHOWN` | The operator is typing the card details by hand (manual / keyed entry, used for MOTO payments). Only delivered over the version-3 read; older reads surface WAITING_FOR_CARD_ENTRY instead. | | `UNKNOWN` | An unknown sub-state. Fallback used for unexpected/new states not recognized by this SDK version. | - **[`PaymentStateReason` enum values (used on `reason`)](#makepaymentandsubscribe-response-reason)** | Name | |------| | `PROCESSING_FAILED_DECLINED_ONLINE` | | `PROCESSING_FAILED_DECLINED_OFFLINE` | | `PROCESSING_FAILED_TIMEOUT` | | `PROCESSING_FAILED_CONNECTION_ERROR` | | `PROCESSING_FAILED_COMM_TIMEOUT` | | `PROCESSING_FAILED_CARD_PROCESSING_ERROR` | | `UNKNOWN` | | `CANCELED_BY_EPOS` | | `CANCELED_BY_USER` | | `EXPIRED` | | `TERMINAL_UNREACHABLE` | | `NOTIFICATION_EXPIRED` | | `SUPERSEDED_BY_NEW_TRANSACTION` | | `FEATURE_NOT_ACTIVATED_UNREFERENCED_REFUNDS` | | `TRANSACTION_ALREADY_IN_PROGRESS` | | `UNSUPPORTED_CURRENCY` | | `COMMUNICATION_FAILED_NETWORK` | | `COMMUNICATION_FAILED_UNEXPECTEDLY` | | `COMMUNICATION_FAILED_AUTH_REQUIRED` | - **[`Metadata` class parameters (used on `metadata`)](#makepaymentandsubscribe-response-metadata)** `Metadata` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata). ## unsubscribeAll Stops all notification events of `makePaymentAndSubscribe->onPaymentStateChanged` related to ongoing payment with `transactionId` and dismisses the Teya UI, if present. ### Request ```json { "jsonrpc": "2.0", "method": "unsubscribeAll", "params": { "transactionId": "my-transaction-id" }, "id": "b20b1a66-974e-3784-8166-a79106f065a1" } ``` - **[Parameters](#unsubscribeall-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transactionId` | `String` | Yes | the id of the ongoing transaction to be unsubscribed from. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "unsubscribeAll->ack" }, "id": "b20b1a66-974e-3784-8166-a79106f065a1" } ``` ## cancelPayment Cancels the ongoing payment request. This is a best effort call, meaning that the Teya payment app may ignore this request, if, for example, it is too late to cancel it. This does NOT cancel the subscribers from getting new state changes, in fact, the listeners will still be the way users can check if this request actually took effect. NOTICE that even if the result is positive, it does not mean that the payment will get cancelled in the end. ### Request ```json { "jsonrpc": "2.0", "method": "cancelPayment", "params": { "transactionId": "my-transaction-id" }, "id": "f0af9f6b-6137-3025-9dc4-7c57ad668242" } ``` - **[Parameters](#cancelpayment-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transactionId` | `String` | Yes | the id of the ongoing transaction to attempt cancellation on. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "cancelPayment->onResult", "result": "CANCELLING_PAYMENT", "debugErrorMessage": "Invalid request" }, "id": "f0af9f6b-6137-3025-9dc4-7c57ad668242" } ``` - **[Parameters](#cancelpayment-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `result` | `String` (enum: `CancellationResult`) | Yes | The result of the cancellation attempt. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | - **[`CancellationResult` enum values (used on `result`)](#cancelpayment-response-result)** | Name | Description | |------|-------------| | `PAYMENT_NOT_YET_CREATED` | Payment not yet created, but communication to create it is under way. Retry when state changes to `NEW`. | | `CANCELLING_PAYMENT` | This is the successful result. It means the system is attempting to cancel the payment request. The payment app may still ignore the cancellation request, if it happens too late in the process. | | `PAYMENT_ALREADY_FINISHED` | The payment was already finished, nothing to cancel. | | `NETWORK_ERROR` | There was a network error when attempting to communicate with the server. | | `UNEXPECTED_SERVER_COMMUNICATION_ERROR` | There was an unexpected error when attempting to communicate with the server. | | `UNKNOWN_TRANSACTION_ID` | Id is not a known ongoing transaction that can be cancelled. | ## refundPayment Refunds the payment for a given `gatewayPaymentId` previously returned via `makePaymentAndSubscribe->onPaymentStateChanged`. ### Request ```json { "jsonrpc": "2.0", "method": "refundPayment", "params": { "gatewayPaymentId": "tr_kxmw734nbfkj3723kndf", "amount": 320, "currency": "GBP", "allocatedLineItems": [ { "externalProductId": "SKU-31241", "allocatedQuantity": 2, "allocatedLineTotal": 200, "allocatedTax": 100 } ] }, "id": "df54e7a4-dfa3-31a8-93dc-4c4b15bcddf5" } ``` - **[Parameters](#refundpayment-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `gatewayPaymentId` | `String` | Yes | corresponding to the payment to refund. | | `amount` | `Int` | Yes | The amount to be refunded, in the smallest unit of the currency. | | `currency` | `String` | Yes | The ISO 4217 currency code (e.g., "GBP", "EUR"). | | `allocatedLineItems` | `array of objects` (class: `AllocatedLineItem`) | No | List of line items objects to be included in the refund. | - **[`AllocatedLineItem` class parameters (used on `allocatedLineItems`)](#refundpayment-request-allocatedlineitems)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `externalProductId` | `String` | Yes | External identifier for the product (e.g., from the partner's system). | | `allocatedQuantity` | `Double` | Yes | Quantity of the item allocated in this transaction. | | `allocatedLineTotal` | `Int` | Yes | Total allocated amount for the line in the smallest currency unit, calculated as (unitGrossPrice × quantity) - lineDiscountAmount. Example: 2 oranges at £1.20 each with a £0.20 discount each → allocatedLineTotal = 200. | | `allocatedTax` | `Int` | No | Allocated tax amount (not percentage) in the smallest currency unit (e.g., 100 pence = £1). | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "refundPayment->onResult", "gatewayRefundId": "refund-123", "result": "SUCCESS", "debugErrorMessage": "Invalid request" }, "id": "df54e7a4-dfa3-31a8-93dc-4c4b15bcddf5" } ``` - **[Parameters](#refundpayment-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `gatewayRefundId` | `String` | No | The id of the newly created refund. | | `result` | `String` (enum: `RefundResult`) | Yes | The final result of the refund. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | - **[`RefundResult` enum values (used on `result`)](#refundpayment-response-result)** | Name | |------| | `SUCCESS` | | `INVALID_AMOUNT_OR_PAYMENT_ID` | | `AMOUNT_EXCEEDS_ALLOWED` | | `DECLINED` | | `NETWORK_ERROR` | | `CANCELLED` | | `FAILED` | ## makeUnreferencedRefund Initiates an unreferenced refund: a card-present credit to the card presented at the card machine, not tied to any original sale. The customer taps their card to receive the money back. Unlike `refundPayment`, which refunds a specific previous payment by its `gatewayPaymentId`, this starts a brand new card-present transaction and reuses the same state machine as `makePaymentAndSubscribe`, so it streams `makeUnreferencedRefund->onPaymentStateChanged` events. IMPORTANT: Because there is no original transaction to validate against, these refunds are subject to additional fraud screening, so they may be declined. Prefer `refundPayment` when you have the original payment id. ### Request ```json { "jsonrpc": "2.0", "method": "makeUnreferencedRefund", "params": { "transactionId": "my-refund-unique-id", "amount": 420, "currency": "GBP", "useTeyaDefaultUi": true }, "id": "914c6c8f-8e44-30c5-a613-e998094a8b71" } ``` - **[Parameters](#makeunreferencedrefund-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transactionId` | `String` | Yes | ePOS unique identifier for this refund, unique within the linked store. | | `amount` | `Int` | Yes | The amount to refund, in the smallest unit of the currency (e.g., cents). | | `currency` | `String` | Yes | The ISO 4217 currency code (e.g., "GBP", "EUR"). | | `useTeyaDefaultUi` | `Boolean` | Yes | If true, the SDK will show a Teya default UI for in progress states and interaction. | ### Response This Response is _streamed_, meaning you will get multiple of these over time for a single `makeUnreferencedRefund` call. However, only the final one will include the "id" in the json-rpc object. Others can be matched via `transactionId`. Represents a refund state change event during an unreferenced refund operation. It shares the same state machine as `MakePaymentStateChange`, so it reuses the `InProgressState` and `PaymentStateReason` enums. ```json { "jsonrpc": "2.0", "result": { "type": "makeUnreferencedRefund->onPaymentStateChanged", "transactionId": "tx-123", "amount": 1000, "currency": "GBP", "gatewayRefundId": "refund-123", "state": "SUCCESSFUL", "inProgressState": "WAITING_FOR_CARD_ENTRY", "isFinal": true, "reason": "CANCELED_BY_USER", "metadata": { "card": { "last4": "1234", "issuingCountry": "GB", "brand": "VISA", "type": "DEBIT" }, "entryMode": "EMV_CONTACTLESS", "verificationMethod": "ONLINE_PIN", "applicationId": "A0000000012345", "merchantAcquiringId": "MID12345", "responseCode": "00", "authorisationCode": "123ABC", "dcc": { "conversionFee": "2.5%", "disclaimer": "I accept to pay in GBP", "exchangeRate": "0.8650", "transactionAmount": 8500, "transactionCurrency": "GBP" } }, "transactionTimestamp": 1733241600000, "debugErrorMessage": "Invalid request" }, "id": "914c6c8f-8e44-30c5-a613-e998094a8b71" } ``` - **[Parameters](#makeunreferencedrefund-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transactionId` | `String` | Yes | The ePOS id passed in the `makeUnreferencedRefund` call. | | `amount` | `Int` | Yes | The total amount that was refunded in minor units. | | `currency` | `String` | Yes | The currency of the `amount`. | | `gatewayRefundId` | `String` | No | Teya backend id for the refund created. This field will not be null on "SUCCESSFUL" state. | | `state` | `String` (enum: `PaymentState`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-paymentstate) | Yes | The current state of the refund, see `PaymentState`. | | `inProgressState` | `String` (enum: `InProgressState`) | No | The detailed state of the refund when in "IN_PROGRESS" state. | | `isFinal` | `Boolean` | Yes | Indicates whether the current state of the refund is final. | | `reason` | `String` (enum: `PaymentStateReason`) | No | The reason for the current refund state, if applicable. | | `metadata` | `object` (class: `Metadata`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata) | No | Additional metadata related to the refund, such as card details or response codes. | | `transactionTimestamp` | `Long` | No | The timestamp (in milliseconds since epoch) when the refund occurred. | | `debugErrorMessage` | `String` | No | useful for logging and reporting issues with Teya. | - **[`PaymentState` enum values (used on `state`)](#makeunreferencedrefund-response-state)** `PaymentState` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-paymentstate). - **[`InProgressState` enum values (used on `inProgressState`)](#makeunreferencedrefund-response-inprogressstate)** `InProgressState` is the same enum used by `makePaymentAndSubscribe` - [see its values ↗](#makepaymentandsubscribe-response-inprogressstate). - **[`PaymentStateReason` enum values (used on `reason`)](#makeunreferencedrefund-response-reason)** `PaymentStateReason` is the same enum used by `makePaymentAndSubscribe` - [see its values ↗](#makepaymentandsubscribe-response-reason). A refund attempted while the feature is switched off for the store reports `FEATURE_NOT_ACTIVATED_UNREFERENCED_REFUNDS`. - **[`Metadata` class parameters (used on `metadata`)](#makeunreferencedrefund-response-metadata)** `Metadata` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata). ## printCustomTemplate Represents a request to print a custom receipt template on the Teya card machine. ### Request ```json { "jsonrpc": "2.0", "method": "printCustomTemplate", "params": { "rows": [ { "rowType": "table", "table": { "headerCells": [ { "element": { "text": "Some text", "bold": true, "align": "CENTER" }, "weight": 0.5 } ], "rows": [ { "cells": [ { "text": "Some text", "bold": true, "align": "CENTER" } ] } ] } } ] }, "id": "e5c962c8-c01e-3a09-8ad3-65737c09bfb9" } ``` - **[Parameters](#printcustomtemplate-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `rows` | `array of objects` (class: `ReceiptRow`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow) | Yes | A list of elements representing the structure and content of the receipt. Each element specifies how a row is displayed, including items, dividers, or other content types. | - **[`ReceiptRow` sealed type (used on `rows`)](#printcustomtemplate-request-rows)** `ReceiptRow` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow). ### Response Represents the change in the state of a printing operation. ```json { "jsonrpc": "2.0", "result": { "type": "printCustom*->onPrintingStateChanged", "receiptId": "a7b8c9d0-1e2f-4a5b-8c9d-0e1f2a3b4c5d", "status": "CONNECTING_TO_PRINTER", "printFailure": "OUT_OF_PAPER", "errorMessage": "Some more info about the reason for error" }, "id": "e5c962c8-c01e-3a09-8ad3-65737c09bfb9" } ``` - **[Parameters](#printcustomtemplate-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `receiptId` | `String` | No | Identifier associated with the receipt being printed. It will be non null for state after `PrintStatus.PENDING`. | | `status` | `String` (enum: `PrintStatus`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printstatus) | Yes | The current status of the printing operation. | | `printFailure` | `String` (enum: `PrintFailure`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printfailure) | No | An optional failure reason if the printing operation has failed. | | `errorMessage` | `String` | No | An optional error message providing additional information about the failure. | - **[`PrintStatus` enum values (used on `status`)](#printcustomtemplate-response-status)** `PrintStatus` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printstatus). - **[`PrintFailure` enum values (used on `printFailure`)](#printcustomtemplate-response-printfailure)** `PrintFailure` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printfailure). ## printCustomImage Represents a method for printing a custom image. ### Request ```json { "jsonrpc": "2.0", "method": "printCustomImage", "params": { "imageFullPath": "Users/Some/Path/ToTheFile/receipt.png" }, "id": "fb25135f-51ff-387e-a13a-1114a8d829e5" } ``` - **[Parameters](#printcustomimage-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `imageFullPath` | `String` | Yes | The absolute or full path of the image file to be printed. | ### Response Represents the change in the state of a printing operation. ```json { "jsonrpc": "2.0", "result": { "type": "printCustom*->onPrintingStateChanged", "receiptId": "a7b8c9d0-1e2f-4a5b-8c9d-0e1f2a3b4c5d", "status": "CONNECTING_TO_PRINTER", "printFailure": "OUT_OF_PAPER", "errorMessage": "Some more info about the reason for error" }, "id": "fb25135f-51ff-387e-a13a-1114a8d829e5" } ``` - **[Parameters](#printcustomimage-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `receiptId` | `String` | No | Identifier associated with the receipt being printed. It will be non null for state after `PrintStatus.PENDING`. | | `status` | `String` (enum: `PrintStatus`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printstatus) | Yes | The current status of the printing operation. | | `printFailure` | `String` (enum: `PrintFailure`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printfailure) | No | An optional failure reason if the printing operation has failed. | | `errorMessage` | `String` | No | An optional error message providing additional information about the failure. | - **[`PrintStatus` enum values (used on `status`)](#printcustomimage-response-status)** `PrintStatus` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printstatus). - **[`PrintFailure` enum values (used on `printFailure`)](#printcustomimage-response-printfailure)** `PrintFailure` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printstatedetailschange-printfailure). ## zipLogs Zips all log files collected from the Teya SDK application and returns a path for the newly created zip file. ### Request ```json { "jsonrpc": "2.0", "method": "zipLogs", "id": "0ff0d1e5-d9ef-3c74-809a-b108e1235bf7" } ``` ### Response ```json { "jsonrpc": "2.0", "result": { "type": "zipLogs->response", "zipPath": "path/to/the/logs.zip" }, "id": "0ff0d1e5-d9ef-3c74-809a-b108e1235bf7" } ``` - **[Parameters](#ziplogs-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `zipPath` | `String` | No | null if there is nothing to zip, the path to the zip file otherwise. | ## openTab Opens a new tab - registers a table/order with POSLink so payment terminals can discover it. Pay at Table lets hospitality staff pull a tab's bill onto a Teya terminal and take payment. The ePOS owns the tab; POSLink keeps a lightweight record for terminal orchestration. ### Request ```json { "jsonrpc": "2.0", "method": "openTab", "params": { "tabId": "ORDER-2026-001", "tabName": "Table 5", "currency": "GBP" }, "id": "b8ba60ff-b96f-3932-923f-ac0565218005" } ``` - **[Parameters](#opentab-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-chosen identifier for this tab. The SDK surfaces it unchanged on every tab model and event. | | `tabName` | `String` | Yes | Display name shown on the terminal's list of open tabs. POSLink does not enforce uniqueness. | | `currency` | `String` | Yes | ISO 4217 currency code that all payments on this tab must use. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "openTab->onResult", "tab": { "tabId": "ORDER-2026-001", "tabName": "Table 5", "status": "PAYING", "totalAmount": 5000, "totalPaid": 2500, "remaining": 2500, "currency": "GBP", "showingBillTerminalId": "term-001", "billFileId": "bill-file-001", "paymentRequests": [ { "eposTransactionId": "tx-123", "status": "SUCCESSFUL", "amount": 2500, "currency": "GBP", "tip": 200, "method": "CARD", "type": "SPLIT", "createdAtEpochMillis": 1733241600000, "updatedAtEpochMillis": 1733241700000, "transactionTimestampEpochMillis": 1733241650000, "metadata": { "card": { "last4": "1234", "issuingCountry": "GB", "brand": "VISA", "type": "DEBIT" }, "entryMode": "EMV_CONTACTLESS", "verificationMethod": "ONLINE_PIN", "applicationId": "A0000000012345", "merchantAcquiringId": "MID12345", "responseCode": "00", "authorisationCode": "123ABC", "dcc": { "conversionFee": "2.5%", "disclaimer": "I accept to pay in GBP", "exchangeRate": "0.8650", "transactionAmount": 8500, "transactionCurrency": "GBP" } } } ], "createdAtEpochMillis": 1733241600000, "updatedAtEpochMillis": 1733241700000 }, "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout" }, "id": "b8ba60ff-b96f-3932-923f-ac0565218005" } ``` - **[Parameters](#opentab-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tab` | `object` (class: `Tab`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab) | No | The opened tab, or null if the request failed. | | `failureReason` | `String` (enum: `TabOperationFailureReason`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason) | No | The reason for the failure, or null if the request succeeded. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`Tab` class parameters (used on `tab`)](#opentab-response-tab)** `Tab` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab). - **[`TabOperationFailureReason` enum values (used on `failureReason`)](#opentab-response-failurereason)** `TabOperationFailureReason` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason). ## listTabs Lists tabs for the linked store, one cursor-paginated page at a time. ### Request ```json { "jsonrpc": "2.0", "method": "listTabs", "params": { "statuses": [ "OPEN" ], "after": "cursor-abc", "before": "cursor-xyz", "limit": 50 }, "id": "30194f0c-9a27-39be-a9fb-4070ccefcbee" } ``` - **[Parameters](#listtabs-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `statuses` | `array of objects` (class: `TabStatusFilter`) | No | Optional filter on tab statuses. When null or empty, the backend default applies (active tabs only: `OPEN`, `PAYING`, `PAUSED`). Pass `COMPLETED`/`CLOSED` to include archived tabs. | | `after` | `String` | No | Opaque cursor from a previous page's `nextCursor`. Mutually exclusive with `before`. | | `before` | `String` | No | Opaque cursor from a previous page's `prevCursor`. Mutually exclusive with `after`. | | `limit` | `Int` | No | Maximum number of items to return. Backend default applies when null. | - **[`TabStatusFilter` enum values (used on `statuses`)](#listtabs-request-statuses)** | Name | Description | |------|-------------| | `OPEN` | Registered and available for terminals. | | `PAYING` | A terminal is processing payment(s). | | `PAUSED` | A split payment was interrupted. | | `COMPLETED` | All payments done, remaining is zero. | | `CLOSED` | Removed from the active list. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "listTabs->onResult", "page": { "items": [ { "tabId": "ORDER-2026-001", "tabName": "Table 5", "status": "OPEN", "totalAmount": 5000, "totalPaid": 0, "remaining": 5000, "currency": "GBP", "showingBillTerminalId": "term-001" } ], "nextCursor": "cursor-next", "prevCursor": "cursor-prev" }, "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout" }, "id": "30194f0c-9a27-39be-a9fb-4070ccefcbee" } ``` - **[Parameters](#listtabs-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | `object` (class: `TabPage`) | No | The requested page of tab summaries, or null if the request failed. | | `failureReason` | `String` (enum: `TabOperationFailureReason`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason) | No | The reason for the failure, or null if the request succeeded. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`TabPage` class parameters (used on `page`)](#listtabs-response-page)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `items` | `array of objects` (class: `TabSummary`) | Yes | The tabs on this page. | | `nextCursor` | `String` | No | Opaque cursor for the next page; null on the last page. | | `prevCursor` | `String` | No | Opaque cursor for the previous page; null on the first page. | - **[`TabSummary` class parameters (used on `items`)](#listtabs-response-page-items)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided identifier for this tab. | | `tabName` | `String` | Yes | Display name shown on the terminal's list of open tabs. | | `status` | `String` (enum: `TabStatus`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabstatus) | Yes | Current lifecycle status. | | `totalAmount` | `Int` | No | Total amount in minor currency units, or null if not yet set. | | `totalPaid` | `Int` | No | Amount paid so far in minor currency units, or null if not yet set. | | `remaining` | `Int` | No | Outstanding balance in minor currency units, or null if not yet set. | | `currency` | `String` | No | ISO 4217 currency code, or null if not yet set. | | `showingBillTerminalId` | `String` | No | Terminal currently displaying the bill, if any. | - **[`TabStatus` enum values (used on `status`)](#listtabs-response-page-items-status)** `TabStatus` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabstatus). - **[`TabOperationFailureReason` enum values (used on `failureReason`)](#listtabs-response-failurereason)** `TabOperationFailureReason` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason). ## getTab Gets full details for a specific tab, including payment history. ### Request ```json { "jsonrpc": "2.0", "method": "getTab", "params": { "tabId": "ORDER-2026-001" }, "id": "2558074f-f328-34fc-bc9e-eadc730f2a74" } ``` - **[Parameters](#gettab-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided tab identifier. | ### Response ```json { "jsonrpc": "2.0", "result": { "type": "getTab->onResult", "tab": { "tabId": "ORDER-2026-001", "tabName": "Table 5", "status": "PAYING", "totalAmount": 5000, "totalPaid": 2500, "remaining": 2500, "currency": "GBP", "showingBillTerminalId": "term-001", "billFileId": "bill-file-001", "paymentRequests": [ { "eposTransactionId": "tx-123", "status": "SUCCESSFUL", "amount": 2500, "currency": "GBP", "tip": 200, "method": "CARD", "type": "SPLIT", "createdAtEpochMillis": 1733241600000, "updatedAtEpochMillis": 1733241700000, "transactionTimestampEpochMillis": 1733241650000, "metadata": { "card": { "last4": "1234", "issuingCountry": "GB", "brand": "VISA", "type": "DEBIT" }, "entryMode": "EMV_CONTACTLESS", "verificationMethod": "ONLINE_PIN", "applicationId": "A0000000012345", "merchantAcquiringId": "MID12345", "responseCode": "00", "authorisationCode": "123ABC", "dcc": { "conversionFee": "2.5%", "disclaimer": "I accept to pay in GBP", "exchangeRate": "0.8650", "transactionAmount": 8500, "transactionCurrency": "GBP" } } } ], "createdAtEpochMillis": 1733241600000, "updatedAtEpochMillis": 1733241700000 }, "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout" }, "id": "2558074f-f328-34fc-bc9e-eadc730f2a74" } ``` - **[Parameters](#gettab-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tab` | `object` (class: `Tab`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab) | No | The requested tab, or null if the request failed. | | `failureReason` | `String` (enum: `TabOperationFailureReason`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason) | No | The reason for the failure, or null if the request succeeded. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`Tab` class parameters (used on `tab`)](#gettab-response-tab)** `Tab` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab). - **[`TabOperationFailureReason` enum values (used on `failureReason`)](#gettab-response-failurereason)** `TabOperationFailureReason` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason). ## closeTab Closes a tab, removing it from the active list. Should be called once payment is complete. POSLink also auto-closes tabs with no activity for 24 hours. ### Request ```json { "jsonrpc": "2.0", "method": "closeTab", "params": { "tabId": "ORDER-2026-001" }, "id": "69957d53-3fca-347f-8c64-72d083bb4114" } ``` - **[Parameters](#closetab-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided tab identifier. | ### Response Result of a `closeTab` call. A null `failureReason` means the tab was closed successfully. ```json { "jsonrpc": "2.0", "result": { "type": "closeTab->onResult", "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout" }, "id": "69957d53-3fca-347f-8c64-72d083bb4114" } ``` - **[Parameters](#closetab-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `failureReason` | `String` (enum: `TabOperationFailureReason`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason) | No | The reason for the failure, or null if the tab was closed. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`TabOperationFailureReason` enum values (used on `failureReason`)](#closetab-response-failurereason)** `TabOperationFailureReason` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason). ## respondToBillRequest Responds to a `subscribeTabEvents->onShowBillRequested` event by sending the bill details to POSLink. The requesting terminal both displays the bill on-screen and can print it on receipt paper, so the supplied template/image should be designed to render legibly in both contexts. ### Request ```json { "jsonrpc": "2.0", "method": "respondToBillRequest", "params": { "tabId": "ORDER-2026-001", "terminalId": "term-001", "totalAmount": 5000, "currency": "GBP", "printModel": [ { "rowType": "table", "table": { "headerCells": [ { "element": { "text": "Some text", "bold": true, "align": "CENTER" }, "weight": 0.5 } ], "rows": [ { "cells": [ { "text": "Some text", "bold": true, "align": "CENTER" } ] } ] } } ] }, "id": "2c63095d-5f1b-36ff-9a88-9322ecc510c6" } ``` - **[Parameters](#respondtobillrequest-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided tab identifier (echoes the value from the event). | | `terminalId` | `String` | Yes | The terminal that requested the bill (echoes the value from the event). | | `totalAmount` | `Int` | Yes | Total bill amount in the smallest currency unit (e.g. pence). | | `currency` | `String` | Yes | ISO 4217 currency code. | | `printModel` | `array of objects` (class: `ReceiptRow`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow) | No | Optional structured receipt template POSLink renders as an itemised bill on the terminal (used for both the on-screen view and the printed copy). Uses the same row structure as `printCustomTemplate`. Ignored when `billImagePath` is set. | | `billImagePath` | `String` | No | Optional absolute path to a pre-rendered bill image (PNG or JPEG), used for both the on-screen view and the printed copy. When set, the SDK uploads the image and `printModel` is not sent. | - **[`ReceiptRow` sealed type (used on `printModel`)](#respondtobillrequest-request-printmodel)** `ReceiptRow` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow). ### Response Result of a `respondToBillRequest` call. A null `failureReason` means POSLink accepted the bill. ```json { "jsonrpc": "2.0", "result": { "type": "respondToBillRequest->onResult", "failureReason": "TOTAL_LESS_THAN_PAID", "debugErrorMessage": "Socket timeout" }, "id": "2c63095d-5f1b-36ff-9a88-9322ecc510c6" } ``` - **[Parameters](#respondtobillrequest-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `failureReason` | `String` (enum: `RespondToBillFailureReason`) | No | The reason for the failure, or null if the bill was accepted. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`RespondToBillFailureReason` enum values (used on `failureReason`)](#respondtobillrequest-response-failurereason)** | Name | Description | |------|-------------| | `NO_LINKED_STORE` | No store is currently linked. Run `setup` (or `setupAuthAndStore`) first. | | `NETWORK_ERROR` | A network error occurred when communicating with the server. | | `TOTAL_LESS_THAN_PAID` | The new total is lower than the amount already paid for the tab. | | `TAB_IN_WRONG_STATE` | The tab can no longer accept this bill (show-bill TTL expired, tab not found, tab CLOSED/COMPLETED, or terminal-id mismatch). | | `UNEXPECTED_ERROR` | An unexpected error occurred; check `debugErrorMessage` for details. | ## respondWithError Rejects a terminal-initiated request (a bill request or a pay request) by sending an error to POSLink. The requesting terminal displays `message` and returns to its table list. ### Request ```json { "jsonrpc": "2.0", "method": "respondWithError", "params": { "tabId": "ORDER-2026-001", "terminalId": "term-001", "errorCode": "TABLE_NOT_FOUND", "message": "Table 5 was not found" }, "id": "3982d2f9-7426-36d4-b26a-e97c79cd6d72" } ``` - **[Parameters](#respondwitherror-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided tab identifier (echoes the value from the originating event). | | `terminalId` | `String` | Yes | The terminal that initiated the request (echoes the value from the event). | | `errorCode` | `String` (enum: `TabErrorCode`) | Yes | The category of error. | | `message` | `String` | Yes | Human-readable text shown to terminal staff alongside the error code. | - **[`TabErrorCode` enum values (used on `errorCode`)](#respondwitherror-request-errorcode)** | Name | Description | |------|-------------| | `TABLE_NOT_FOUND` | The tab/order no longer exists on the ePOS. | | `BILL_ALREADY_SETTLED` | The bill was already settled outside Pay at Table. | | `EPOS_ERROR` | Generic ePOS-side failure with no more specific category. | | `REQUEST_REJECTED` | The ePOS explicitly rejects the request (e.g. a policy decision). | ### Response Result of a `respondWithError` call. A null `failureReason` means POSLink accepted the rejection. ```json { "jsonrpc": "2.0", "result": { "type": "respondWithError->onResult", "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout" }, "id": "3982d2f9-7426-36d4-b26a-e97c79cd6d72" } ``` - **[Parameters](#respondwitherror-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `failureReason` | `String` (enum: `TabOperationFailureReason`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason) | No | The reason for the failure, or null if the rejection was accepted. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`TabOperationFailureReason` enum values (used on `failureReason`)](#respondwitherror-response-failurereason)** `TabOperationFailureReason` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason). ## subscribeTabEvents Subscribes to the tab event stream for the linked store. This is a _streamed_ call. Tab events arrive as JSON-RPC notifications (messages with no `id`), each carrying one of these results in its `result.type`: - `subscribeTabEvents->onShowBillRequested` - a terminal asks to display a tab's bill. - `subscribeTabEvents->onPayRequested` - a terminal initiates a payment on a tab. - `subscribeTabEvents->onPaymentProgress` - an intermediate payment progress update. - `subscribeTabEvents->onPaymentCompleted` - a single payment on a tab reached a final state. - `subscribeTabEvents->onTabPaused` - a terminal paused a split payment. - `subscribeTabEvents->onTabResumed` - a paused tab resumed. - `subscribeTabEvents->onTabCompleted` - a tab's outstanding balance reached zero. - `subscribeTabEvents->onBillHidden` - the terminal showing a bill exited without paying. - `subscribeTabEvents->onConnectionStateChange` - the stream's connection state changed. The response section below shows one representative event; the others share the same envelope. The stream ends with a single final response - carrying the original request `id` and a `subscribeTabEvents->onConnectionStateChange` result with `state: DISCONNECTED` - when the store link is cleared or `unsubscribeTabEvents` is called. Only one subscription may be active at a time; calling `subscribeTabEvents` again while one is live is rejected with an invalid-state error. ### Request ```json { "jsonrpc": "2.0", "method": "subscribeTabEvents", "id": "8802ec5a-d114-34c9-8abe-d0ac74aca8b1" } ``` ### Response The terminal currently showing a tab's bill exited without paying (or timed out). ```json { "jsonrpc": "2.0", "result": { "type": "subscribeTabEvents->onBillHidden", "tabId": "ORDER-2026-001" }, "id": "8802ec5a-d114-34c9-8abe-d0ac74aca8b1" } ``` - **[Parameters](#subscribetabevents-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The identifier of the tab whose bill was hidden. | ## unsubscribeTabEvents Stops the active tab event stream started by `subscribeTabEvents`. The streamed `subscribeTabEvents` call then completes with its final `DISCONNECTED` response. A no-op if no subscription is active. ### Request ```json { "jsonrpc": "2.0", "method": "unsubscribeTabEvents", "id": "33362d8f-a522-38ab-8fee-5b28b8dcb738" } ``` ### Response Acknowledges that the tab event stream was stopped. ```json { "jsonrpc": "2.0", "result": { "type": "unsubscribeTabEvents->ack" }, "id": "33362d8f-a522-38ab-8fee-5b28b8dcb738" } ``` ## setPayAtTableEnabledOnStore Enables or disables Pay at Table at the **store** level for the currently linked store. Sets a store-wide capability flag. When enabled, every terminal in the store can surface PAT entry points; when disabled those entry points are hidden the next time staff attempt them. Each terminal keeps its own local opt-out toggle (default ON) - this call does not change that. Disabling is an entry-point gate only: any PAT session already in progress on a terminal runs to completion. Propagation to terminals is best-effort and asynchronous; a successful result means POSLink accepted the store-level setting. ### Request ```json { "jsonrpc": "2.0", "method": "setPayAtTableEnabledOnStore", "params": { "enable": true }, "id": "f6e65960-6606-3656-84e4-dbfe41fe946a" } ``` - **[Parameters](#setpayattableenabledonstore-request-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `enable` | `Boolean` | Yes | `true` to enable PAT for the store, `false` to disable it. | ### Response Result of a `setPayAtTableEnabledOnStore` call. A null `failureReason` means POSLink accepted the new setting. ```json { "jsonrpc": "2.0", "result": { "type": "setPayAtTableEnabledOnStore->onResult", "failureReason": "NETWORK_ERROR", "debugErrorMessage": "Socket timeout" }, "id": "f6e65960-6606-3656-84e4-dbfe41fe946a" } ``` - **[Parameters](#setpayattableenabledonstore-response-parameters)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `failureReason` | `String` (enum: `TabOperationFailureReason`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason) | No | The reason for the failure, or null if the setting was accepted. | | `debugErrorMessage` | `String` | No | Useful for logging and reporting issues with Teya. | - **[`TabOperationFailureReason` enum values (used on `failureReason`)](#setpayattableenabledonstore-response-failurereason)** `TabOperationFailureReason` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-taboperationfailurereason). ## General Definitions ### `PrintFailure` | Name | |------| | `NETWORK_ERROR` | | `BUSY` | | `OUT_OF_PAPER` | | `OVERHEATED` | | `COVER_OPEN` | | `LOW_BATTERY` | | `OTHER` | ### `PrintStatus` | Name | |------| | `PENDING` | | `CONNECTING_TO_PRINTER` | | `PRINTING` | | `PRINTED` | | `FAILED` | ### `Response` | Name | Description | |------|-------------| | `SUCCESS` | setup was successful | | `CANCELED` | setup flow UI was canceled by the user | | `SERVER_ERROR` | setup failed unexpectedly from a server error, check `debugErrorMessage` for details | ## Payments Definitions ### `Metadata` | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `card` | `object` (class: `Card`) | No | The card details used for the payment, including last 4 digits, issuing country, brand, and type. | | `entryMode` | `String` (enum: `EntryMode`) | No | The method used to enter the payment details (e.g., EMV, contactless, keyed). | | `verificationMethod` | `String` (enum: `VerificationMethod`) | No | The method used to verify the payment (e.g., PIN, signature). | | `applicationId` | `String` | No | The application ID used during the payment process. | | `merchantAcquiringId` | `String` | No | The merchant acquiring ID associated with the payment. | | `responseCode` | `String` | No | The response code returned by the payment gateway. | | `authorisationCode` | `String` | No | The authorisation code provided for the payment. | | `dcc` | `object` (class: `Dcc`) | No | The Dynamic Currency Conversion (DCC) details, null if DCC was not used. | - **[`Card` class parameters (used on `card`)](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata-card)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `last4` | `String` | Yes | The last 4 digits of the card number. | | `issuingCountry` | `String` | No | The country where the card was issued (ISO 3166-1 alpha-2). | | `brand` | `String` (enum: `CardBrand`) | Yes | The brand of the card (e.g., Visa, Mastercard). | | `type` | `String` (enum: `CardType`) | No | The type of the card (e.g., debit, credit). | - **[`CardBrand` enum values (used on `brand`)](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata-card-brand)** | Name | |------| | `VISA` | | `MAESTRO` | | `MASTERCARD` | | `UNION_PAY` | | `JCB` | | `DINERS` | | `AMEX` | | `OTHER` | - **[`CardType` enum values (used on `type`)](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata-card-type)** | Name | |------| | `DEBIT` | | `CREDIT` | | `PREPAID` | | `CHARGE` | | `PRIVATE` | | `DEFERRED_DEBIT` | | `UNKNOWN` | - **[`EntryMode` enum values (used on `entryMode`)](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata-entrymode)** | Name | |------| | `E_COM` | | `EMV_PIN` | | `CONTACT_ICC` | | `EMV_CONTACTLESS` | | `KEYED` | | `MAGSTRIPE_SWIPED` | | `ON_FILE` | | `MAGSTRIPE_FALLBACK` | - **[`VerificationMethod` enum values (used on `verificationMethod`)](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata-verificationmethod)** | Name | |------| | `NONE` | | `ELECTRONIC_SIGNATURE` | | `ON_DEVICE` | | `MANUAL` | | `SIGNATURE` | | `OFFLINE_PIN` | | `ONLINE_PIN` | | `OFFLINE_PIN_PLUS_SIGNATURE` | | `SECURED_ELECTRONIC_COMMERCE` | - **[`Dcc` class parameters (used on `dcc`)](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata-dcc)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `conversionFee` | `String` | Yes | Conversion fee applied for DCC service, represented as a percentage string. | | `disclaimer` | `String` | Yes | Text that should be printed on the customer's receipt confirming DCC acceptance. | | `exchangeRate` | `String` | Yes | Exchange rate applied for DCC conversion (e.g. "0.8650" means 1 EUR (merchant currency) = 0.8650 GBP (cardholder currency)). | | `transactionAmount` | `Int` | Yes | Transaction amount in the smallest currency unit (8500 = £85.00). | | `transactionCurrency` | `String` | Yes | Currency used by the cardholder in ISO 4217 format. | ### `PaymentState` | Name | Description | |------|-------------| | `PENDING` | Initial temporary state of the payment. It will be the local state until we get the response of the payment creation. | | `NEW` | Temporary state which means the payment request has been created. This state is set when the payment request is created on the server successfully. PosLink will have sent a push notification to the Teya payment app at this point. | | `IN_PROGRESS` | Temporary state which means we got acknowledgement from the Teya payment app that the payment is in progress. This state is set when the Teya payment app updates the state to IN_PROGRESS in the backend. At this point, the reading card screen would be shown in the Teya app. | | `CANCELLING` | Temporary state which means the system is trying to cancel the payment. It is possible that the payment will not be cancelled and moved back to `IN_PROGRESS` or `SUCCESSFUL` / `PROCESSING_FAILED`. This state is set when the `cancelPayment` succeeds and the server got the request to cancel. | | `CANCELED` | Final state which means the payment was cancelled. | | `SUCCESSFUL` | Final state which means the payment was successful. | | `PROCESSING_FAILED` | Final state which means the payment was not successful. Check `reason` for why that may have happened. | | `COMMUNICATION_FAILED` | Final state which means there was a communication failure either when trying to create the payment or when trying to get state updates. If we got `PENDING` -> `COMMUNICATION_FAILED` it means the payment was never created (or for state reason `PaymentStateReason.COMMUNICATION_FAILED_NETWORK` specifically, we may not know if the payment was created or not). If we got any state other than `PENDING` -> `COMMUNICATION_FAILED` it means the updating flow failed unexpectedly. (state reason will be `PaymentStateReason.COMMUNICATION_FAILED_UNEXPECTEDLY`) or `PaymentStateReason.COMMUNICATION_FAILED_AUTH_REQUIRED` - in which case you should setup PosLink again after clearing the auth info) | ## Printing Definitions ### `Align` | Name | |------| | `LEFT` | | `CENTER` | | `RIGHT` | ### `ReceiptRow` This is a sealed type with discriminator `rowType`. On json object, specify the wanted type with, for example: `"rowType" : "divider"` The following table shows the possible types: | rowType | Type | |------|-------------| | `divider` | `Divider` | | `item` | `object` (class: `Item`) | | `items` | `object` (class: `Items`) | | `spacer` | `Spacer` | | `table` | `object` (class: `Table`) | - **[`Item` class parameters (used on `ReceiptRow.item`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-item)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `item` | `object` (class: `RowElement`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement) | Yes | single item. | - **[`RowElement` sealed type (used on `item`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-item-item)** `RowElement` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement). - **[`Items` class parameters (used on `ReceiptRow.items`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-items)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `items` | `array of objects` (class: `RowElement`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement) | Yes | row items. | - **[`RowElement` sealed type (used on `items`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-items-items)** `RowElement` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement). - **[`Table` class parameters (used on `ReceiptRow.table`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-table)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `headerCells` | `array of objects` (class: `TableHeaderCell`) | Yes | A list of header cells that represent the columns of the table. Each header cell describes a column's content or purpose. | | `rows` | `array of objects` (class: `TableRow`) | Yes | A list of rows in the table, where each row contains an ordered list of text cells corresponding to the headers. | - **[`TableHeaderCell` class parameters (used on `headerCells`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-table-headercells)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `element` | `object` (class: `Text`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text) | Yes | The text element to be displayed within the header cell. | | `weight` | `Float` | No | The proportional weight of the cell compared to others in the same row. | - **[`Text` class parameters (used on `element`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-table-headercells-element)** `Text` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text). - **[`TableRow` class parameters (used on `rows`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-table-rows)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cells` | `array of objects` (class: `Text`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text) | Yes | A list of text elements that make up the contents of the row. | - **[`Text` class parameters (used on `cells`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-receiptrow-receiptrow-table-rows-cells)** `Text` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text). ### `RowElement` This is a sealed type with discriminator `elementType`. On json object, specify the wanted type with, for example: `"elementType" : "image"` The following table shows the possible types: | elementType | Type | |------|-------------| | `image` | `object` (class: `Image`) | | `qrCode` | `object` (class: `QrCode`) | | `text` | `object` (class: `Text`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text) | - **[`Image` class parameters (used on `RowElement.image`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-rowelement-image)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `imageFullPath` | `String` | Yes | Specifies the full path to the image resource. | | `align` | `String` (enum: `Align`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-align) | No | Specifies the alignment of the image. Default is `Align.LEFT`. | - **[`Align` enum values (used on `align`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-rowelement-image-align)** `Align` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-align). - **[`QrCode` class parameters (used on `RowElement.qrCode`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-rowelement-qrcode)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | `String` | Yes | The URL or data encoded in the QR code. | | `align` | `String` (enum: `Align`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-align) | No | Specifies the alignment of the QR code within the row. Default is `Align.LEFT`. | - **[`Align` enum values (used on `align`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-rowelement-qrcode-align)** `Align` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-align). - **[`Text` class parameters (used on `RowElement.text`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-rowelement-text)** `Text` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text). ### `Text` | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `text` | `String` | Yes | The text content of the element. | | `bold` | `Boolean` | No | Indicates whether the text should be displayed in bold. | | `align` | `String` (enum: `Align`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-align) | No | Specifies the alignment of the text. Default is `Align.LEFT`. | - **[`Align` enum values (used on `align`)](#def-com-teya-unifiedepssdk-rpcmodels-printing-rowelement-text-align)** `Align` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-printing-align). ## Setup Definitions ### `Store` | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `String` | Yes | store id. | | `name` | `String` | Yes | store name. | | `address` | `object` (class: `StoreAddress`) | Yes | store address. | - **[`StoreAddress` class parameters (used on `address`)](#def-com-teya-unifiedepssdk-rpcmodels-setup-store-address)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `city` | `String` | Yes | The city where the store is located. | | `country` | `String` | Yes | The country where the store is located. | | `streetAddressLine1` | `String` | Yes | The first line of the street address. | | `streetAddressLine2` | `String` | No | The second line of the street address, if applicable. | | `zipcode` | `String` | Yes | The postal code for the store's address. | ### `Terminal` | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `String` | Yes | The unique identifier of the terminal. | | `name` | `String` | Yes | The human-readable name of the terminal. | | `serialNumber` | `String` | Yes | The serial number of the terminal. | ## Tabs Definitions ### `Tab` | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tabId` | `String` | Yes | The ePOS-provided identifier for this tab. | | `tabName` | `String` | Yes | Display name shown on the terminal's list of open tabs. | | `status` | `String` (enum: `TabStatus`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabstatus) | Yes | Current lifecycle status. | | `totalAmount` | `Int` | No | Total amount in minor currency units, or null if not yet set. | | `totalPaid` | `Int` | No | Amount paid so far in minor currency units, or null if not yet set. | | `remaining` | `Int` | No | Outstanding balance in minor currency units, or null if not yet set. | | `currency` | `String` | No | ISO 4217 currency code, or null if not yet set. | | `showingBillTerminalId` | `String` | No | Terminal currently displaying the bill, if any. | | `billFileId` | `String` | No | Identifier of an uploaded bill image, if any. | | `paymentRequests` | `array of objects` (class: `TabPaymentRequestSummary`) | No | Payments recorded against this tab so far. | | `createdAtEpochMillis` | `Long` | Yes | Tab creation time as Unix epoch milliseconds (UTC). | | `updatedAtEpochMillis` | `Long` | Yes | Last update time as Unix epoch milliseconds (UTC). | - **[`TabStatus` enum values (used on `status`)](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab-status)** `TabStatus` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabstatus). - **[`TabPaymentRequestSummary` class parameters (used on `paymentRequests`)](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab-paymentrequests)** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `eposTransactionId` | `String` | Yes | The ePOS id of the payment. | | `status` | `String` (enum: `PaymentState`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-paymentstate) | Yes | Current status of the payment. | | `amount` | `Int` | Yes | The charged amount in the smallest currency unit, inclusive of tip. | | `currency` | `String` | Yes | ISO 4217 currency code of the amount and tip. | | `tip` | `Int` | No | Optional tip amount in the smallest currency unit. | | `method` | `String` (enum: `TabPaymentMethod`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymentmethod) | No | How the customer paid. | | `type` | `String` (enum: `TabPaymentType`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymenttype) | Yes | Whether the payment covered the full amount or a split portion. | | `createdAtEpochMillis` | `Long` | No | Payment creation time as Unix epoch milliseconds (UTC), when known. | | `updatedAtEpochMillis` | `Long` | No | Last update time as Unix epoch milliseconds (UTC), when known. | | `transactionTimestampEpochMillis` | `Long` | No | When the terminal completed the transaction, as Unix epoch milliseconds (UTC). Set only on successful payments. | | `metadata` | `object` (class: `Metadata`) - [definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata) | No | Transaction metadata. Set only on successful card payments. | - **[`PaymentState` enum values (used on `status`)](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab-paymentrequests-status)** `PaymentState` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-paymentstate). - **[`TabPaymentMethod` enum values (used on `method`)](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab-paymentrequests-method)** `TabPaymentMethod` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymentmethod). - **[`TabPaymentType` enum values (used on `type`)](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab-paymentrequests-type)** `TabPaymentType` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tabpaymenttype). - **[`Metadata` class parameters (used on `metadata`)](#def-com-teya-unifiedepssdk-rpcmodels-tabs-tab-paymentrequests-metadata)** `Metadata` is a shared type - [check its definition ↗](#def-com-teya-unifiedepssdk-rpcmodels-payments-metadata). ### `TabOperationFailureReason` | Name | Description | |------|-------------| | `NO_LINKED_STORE` | No store is currently linked. Run `setup` (or `setupAuthAndStore`) first. | | `NETWORK_ERROR` | A network error occurred when communicating with the server. | | `UNEXPECTED_ERROR` | An unexpected error occurred; check `debugErrorMessage` for details. | ### `TabPaymentMethod` | Name | Description | |------|-------------| | `CARD` | Card payment taken on the terminal. | | `CASH` | Cash recorded on the terminal (tracked only, no card action). | ### `TabPaymentType` | Name | Description | |------|-------------| | `FULL` | Paying the full outstanding amount in a single transaction. | | `SPLIT` | Paying a portion of the bill (one payer in a split). | ### `TabStatus` | Name | Description | |------|-------------| | `OPEN` | Registered and available for terminals. | | `PAYING` | A terminal is processing payment(s). | | `PAUSED` | A split payment was interrupted. | | `COMPLETED` | All payments done, remaining is zero. | | `CLOSED` | Removed from the active list. | | `UNKNOWN` | Status not recognised by this SDK version. |