Physical POS
The Physical POS API has two parts:
- Payment endpoints: from your own server you start sales, pre-authorisations and refunds on the POS device in your store, reverse payments and receive the outcome by webhook; you read your transactions, reports and end-of-day records. → Start a Payment · Payment Flow
- Management endpoints: you manage the records of your POS setup: stores and registers, logical terminals, the terminals' bank details (merchant and terminal numbers), devices and the device linked to each terminal.
Quick start: to start your first payment step by step, from choosing the device to getting the outcome → Start a Payment.
You see and edit the same records in the panel; the API and the panel work on the same data. Vendor accounts (the details of your account with a POS vendor) are managed only in the panel; there is no API for them. Resolving a payment with an uncertain outcome with evidence is also done in the panel only.
The payment endpoints work when a payment capability definition exists for the target device's model. On a device without a capability definition, starting a payment and a reversal get 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) and no payment record is created. Fiscal document events (physical_pos.fiscal_document.*) are not produced at the moment; you can subscribe to them. → Payment Flow
What it offers
| Capability | Description |
|---|---|
| Payment operations | Sales on a device (single payment and instalments), void, full, partial and itemized refunds, pre-authorisation, cancel before start, unmatched refund; retrieving and listing payments; following up an uncertain outcome. → Sale · Void · Refund · Partial Refund |
| Items | Start a sale with product lines, tax breakdown per line and refunds by quantity. → Sale Items · Itemized Refund |
| Transactions | List payments together with their reversals, payments with an uncertain outcome and a transaction's timeline. → Transactions |
| Reports | Sales summary by day, store, device or instrument, and tax summary. → Reports |
| End-of-day records | The devices' end-of-day results and their difference from Lunixi's records. → End-of-Day Records |
| Webhook events | Notifications of payment and fiscal document outcomes. → Webhook Events |
| Catalog | POS vendors, device models (with images) and the banks usable on physical POS, as defined on the platform. Read-only. → Catalog |
| Stores | Create, update, archive and restore stores; per-store change history. → Stores |
| Registers | Registers that belong to a store; create, rename, archive and restore. → Registers |
| Logical terminals | The terminal records that accept payments: terminal code, vendor, vendor-side identifiers, status and closure. → Logical Terminals |
| Bank rows | A terminal's merchant number (MID), terminal number (TID) and currencies at each bank. → Bank Rows |
| Devices | Register physical POS devices, activate, suspend and put them into maintenance, assign them to a store or register, move them to storage and retire them; assignment and change history. → Devices |
| Device link | Replace the device linked to a terminal or unlink it; link history. → Device Link |
| Device identity | Issue and revoke activation codes for a device, list and revoke the device's identity keys, revert an enrollment made with an activation code. → Device Identity |
| Overview counts | Active and archived store and register counts, open and closed terminal counts, device counts by status. → Overview Counts |
Core concepts
Store and register
A store is a point of sale of your business (branch, shop, service point). A register is a checkout point inside a store and always belongs to exactly one store; a register is never moved to another store.
Stores and registers are environment-less: the test and live environments see the same store and register records. → Environments
Stores and registers are not deleted, they are archived. An archived record keeps its code and can be restored. When a store is archived, its active registers are archived in the same operation; when the store is restored, the registers stay archived.
Device and logical terminal
Physical POS has two separate records:
| Record | What it is | Example |
|---|---|---|
| Device | The hardware you hold: a POS device with a vendor, a model and a serial number. | A countertop POS in a store |
| Logical terminal | The identity that accepts payments: the terminal code, the vendor and the merchant and terminal numbers at the banks live on this record. | The terminal with code IST-KADIKOY-01 |
When the device changes (fault, loss, renewal), the logical terminal and its bank details stay the same; only the device linked to the terminal changes. This relation is called the device link:
- A terminal has at most one linked device at a time.
- A device is linked to at most one terminal at a time.
A logical terminal is environment-bound: every terminal is in either the test or the live environment, and this never changes.
The chain
The records connect like this:
A logical terminal is not attached to a store directly but through its linked device: the device is assigned to a store (and optionally to one of that store's registers), and the terminal is linked to that device. This is why the terminal's identity and bank details are kept even when the device changes.
Catalog
The catalog is shared reference data across the platform: vendors, device models and banks. You only read it. The vendorCode you use when creating a terminal comes from the vendor list; the vendorAcquirerRef on a bank row is mapped to a catalog bank through the vendor's bank code mapping.
Payment and reversal
A payment always runs on a device, on the logical terminal the device is linked to. When you start a payment the request is accepted with 202; you receive the outcome by webhook. Reversals such as void, refund and pre-authorisation close are separate payment records linked to the original payment: the original payment is the root, a reversal is a child payment. A root together with its reversals is a transaction. → Payment Flow
Endpoints
All endpoints, the scopes they require and the pages that cover them: Endpoint Index. These endpoints need a request signed with your API key. → Authentication and Scopes