Physical POS
Preparing a Device for Payments

Preparing a Device for Payments

For a POS device to take payments, its records must be in place, your ownership of the device must be verified and the device must be connected to Lunixi. This page walks through preparing a device for payments from scratch.

Setup steps

StepWhat you doEndpoint
1Create the store and, optionally, the register.POST /stores, POST /stores/{storeId}/registers → Stores · Registers
2Register the device; if you send storeId, the device is assigned to that store. The device starts with lifecycleStatus: "PENDING" and ownershipStatus: "UNVERIFIED".POST /devices → Devices
3Pair the device: the Lunixi app on the device shows a code on its screen; you enter and approve the code in the panel. The paired device is verified and becomes ACTIVE.Panel: Devices › Add device with code or device detail › Identity → Device Identity
4Add the logical terminal and the merchant and terminal IDs at the banks (bank rows).POST /terminals, POST /terminals/{terminalId}/acquirers → Logical Terminals · Bank Rows
5Link the device to the terminal.POST /terminals/{terminalId}/device-link → Device Link
6Check that the device is ready for payments: presence.decision: "READY".GET /devices/{deviceId} → Devices › Connection status
  • The terminal's verification comes from the device: when a verified device is linked to the terminal, the terminal is verified too. If you link the device first and pair it afterwards, the terminal is verified by the pairing.
  • When a device is replaced, steps 1, 4 and 6 are not repeated: you register and pair the new device and link it to the terminal; the terminal and bank rows stay the same.
  • To suspend a device or put it into maintenance: Devices › Lifecycle.

Before it can take payments

Preparing a device for paymentsCreate the store and register, register the device as PENDING, pair it by approving the code on its screen in the panel so it becomes verified and ACTIVE, add the terminal and bank row, link the device to the terminal, and take payments once the device is ready.1Store and registerPOST /stores2Register devicePOST /devicesPENDING3Pairingapprove code in panelVERIFIED · ACTIVE4Terminal and bankPOST /terminals…/acquirers5Device link…/device-link6Ready for paymentspresence READYLEGENDAPIPANEL AND DEVICE SCREENRESULT
A paired device is verified and becomes ACTIVE on its own. You see whether the device is ready in presence.decision.

A payment always runs on a device, on the logical terminal the device is linked to. For the device to take a payment:

ConditionWhere you see itOtherwise
The device is activelifecycleStatus: "ACTIVE" on the device409 physical_pos.payment.device_not_payable (details.reason: lifecycle_<status>)
The device's ownership is verifiedownershipStatus: "VERIFIED" on the device409 physical_pos.payment.device_not_payable (ownership_unverified)
A communication channel is setintegrationChannel is not UNSET on the device422 physical_pos.payment.operation_unsupported (channel_unset)
The device is linked to a terminallogicalTerminal is filled on the device409 physical_pos.payment.terminal_not_payable (not_linked)
The terminal is active and verifiedterminalStatus: "ACTIVE", ownershipStatus: "VERIFIED" on the terminal409 physical_pos.payment.terminal_not_payable (status_<status> or ownership_unverified)
The device is ready for paymentpresence.decision: "READY" on the device409 physical_pos.payment.device_offline or 503 physical_pos.presence.unavailable → Step 1

Registering a device, assigning it to a store and linking it to a terminal: Devices · Device Link.

Bank row (optional). To route the payment through a specific bank, send the id of one of the terminal's bank rows as terminalAcquirerId. The row must be acquirerStatus: "ACTIVE" and mappingStatus: "MAPPED" and carry the payment's currency in currencies. If you do not send it, the device chooses the bank. → Payments › Bank row

Checking the application version

The Android source includes a Device → Application version card. It shows the running version, the release offered to this device, its distribution channel and the last verification time. Withdrawn builds and versions below the recommended minimum are shown as warnings. Manifest v1 uses NOTICE_ONLY: the minimum-version notice does not block payments.

The information comes from the existing signed, device-only app-release contract; your merchant API key is not used on the device. The manifest is bound to the organization, device, environment, package, device composition and installed version. Its Ed25519 signature, validity, revision and compatibility must pass verification before activation. The last valid copy is stored encrypted. Failed refreshes show it as historical information. An old build's warnings are not applied to a newly installed build, while the revision rollback floor survives.

MQTT RELEASE_AVAILABLE is a refresh hint, never an installation command. Notifications coalesce with 0–300 seconds of jitter; connection, foreground entry and manifest half-life can also trigger a refresh. Manual checks and hints cannot bypass quota cooldowns or Retry-After. Distribution channels (Google Play, manufacturer store, MDM or Lunixi) are separate from MQTT transport channels.

Delivery boundary: the source-level version reader is implemented. APK download/installation, installation reports and physical-device acceptance remain separate work. A displayed offer does not prove that an APK was downloaded, installed or deployed to production. The installer must preserve active/UNKNOWN payments, settlement, pending device events and journal/Keystore continuity; uninstalling or clearing application data is not a recovery path.