Physical POS
Overview

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

CapabilityDescription
Payment operationsSales 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
ItemsStart a sale with product lines, tax breakdown per line and refunds by quantity. → Sale Items · Itemized Refund
TransactionsList payments together with their reversals, payments with an uncertain outcome and a transaction's timeline. → Transactions
ReportsSales summary by day, store, device or instrument, and tax summary. → Reports
End-of-day recordsThe devices' end-of-day results and their difference from Lunixi's records. → End-of-Day Records
Webhook eventsNotifications of payment and fiscal document outcomes. → Webhook Events
CatalogPOS vendors, device models (with images) and the banks usable on physical POS, as defined on the platform. Read-only. → Catalog
StoresCreate, update, archive and restore stores; per-store change history. → Stores
RegistersRegisters that belong to a store; create, rename, archive and restore. → Registers
Logical terminalsThe terminal records that accept payments: terminal code, vendor, vendor-side identifiers, status and closure. → Logical Terminals
Bank rowsA terminal's merchant number (MID), terminal number (TID) and currencies at each bank. → Bank Rows
DevicesRegister 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 linkReplace the device linked to a terminal or unlink it; link history. → Device Link
Device identityIssue 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 countsActive 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:

RecordWhat it isExample
DeviceThe hardware you hold: a POS device with a vendor, a model and a serial number.A countertop POS in a store
Logical terminalThe 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:

Physical POS record chainA register sits inside a store; a device is assigned to a store or register; a logical terminal is linked one to one to a device and carries the merchant and terminal IDs at the banks in its bank rows.STORE · NO ENVIRONMENTASSIGN1 : 11 : NRegisteroptionalDeviceserial · modelLogical terminalterminalCodeBank rowsMID · TIDTEST · LIVEdevice changes, terminal staysLEGENDRECORDTAKES PAYMENTSBANK DETAILSCONTAINER
If a device fails or is replaced, only the device link changes; the terminal code and bank rows stay the same.

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

Pages in this section