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
| Step | What you do | Endpoint |
|---|---|---|
| 1 | Create the store and, optionally, the register. | POST /stores, POST /stores/{storeId}/registers → Stores · Registers |
| 2 | Register 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 |
| 3 | Pair 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 |
| 4 | Add the logical terminal and the merchant and terminal IDs at the banks (bank rows). | POST /terminals, POST /terminals/{terminalId}/acquirers → Logical Terminals · Bank Rows |
| 5 | Link the device to the terminal. | POST /terminals/{terminalId}/device-link → Device Link |
| 6 | Check 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
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:
| Condition | Where you see it | Otherwise |
|---|---|---|
| The device is active | lifecycleStatus: "ACTIVE" on the device | 409 physical_pos.payment.device_not_payable (details.reason: lifecycle_<status>) |
| The device's ownership is verified | ownershipStatus: "VERIFIED" on the device | 409 physical_pos.payment.device_not_payable (ownership_unverified) |
| A communication channel is set | integrationChannel is not UNSET on the device | 422 physical_pos.payment.operation_unsupported (channel_unset) |
| The device is linked to a terminal | logicalTerminal is filled on the device | 409 physical_pos.payment.terminal_not_payable (not_linked) |
| The terminal is active and verified | terminalStatus: "ACTIVE", ownershipStatus: "VERIFIED" on the terminal | 409 physical_pos.payment.terminal_not_payable (status_<status> or ownership_unverified) |
| The device is ready for payment | presence.decision: "READY" on the device | 409 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.