Physical POS
Connection Methods

Connection Methods

Whichever device you start the payment on, you send the same request: POST /api/v1/physical-pos/payments. Lunixi chooses the path the request takes to the device from the connection method (integrationChannel) in the device record. Your code needs no branching by connection method; the request, the response, the webhooks and the error codes are the same for every method.

Connection methods

How a payment request reaches the deviceOn the APP2APP and LOCAL_REST paths Lunixi sends the command to the Lunixi app on the device, which starts the payment through the payment app or the device's local interface; on the VENDOR_CLOUD path Lunixi sends the request to the vendor cloud, which starts the payment on the device.APP2APPLOCAL_RESTVENDOR_CLOUDSTARTSLOCAL APISTARTSLunixisigned commandLunixi appon device · always onLunixi appon device · always onVendor cloudyour vendor accountPayment appon deviceLocal interfaceon devicePOS deviceonlineThe path comes from the device's integrationChannel.Device not ready: 409 device_offline, no queue.Lunixi never resends by another path on its own.LEGENDLUNIXION DEVICEVENDOR
Each device works over its one recorded path. If a path fails, the payment is not sent by another path automatically; this prevents charging the same payment twice.
integrationChannelWhat the device needsHow Lunixi delivers the requestWhen it fits
APP2APPThe Lunixi app is installed and running.Sends a signed command over the secure, always-on connection the app keeps with Lunixi. The app verifies the command and starts the payment app on the device.Models where you can install the Lunixi app and the payment app can be started by another app.
LOCAL_RESTThe Lunixi app is installed and running.The command reaches the app over the same secure, always-on connection. The app starts the payment through the device's own local interface.Models whose payment app offers a local interface on the device.
VENDOR_CLOUDNo Lunixi app is needed. The device must be on and connected to the internet, and linked to the vendor account you defined under Integrations in the panel (vendorAccount filled in the device detail).Forwards the request, with your vendor account's credentials, to the device vendor's cloud service; the cloud service starts the payment on the device.When you use the device through the vendor's cloud service without installing an app on it.

UNSET means no connection method is set; no payment can be started on such a device (422 physical_pos.payment.operation_unsupported, channel_unset). appMode (such as CASHIER or KIOSK) is used only with APP2APP and LOCAL_REST, which run with the Lunixi app.

Seeing and changing the connection method

  • Setting it: You set it with the integrationChannel field when you register the device (in the panel or with POST /api/v1/physical-pos/devices). → Devices › Register a device
  • Seeing it: In the panel, on the device detail; in the API, in the integrationChannel field of the device list and of GET /api/v1/physical-pos/devices/{deviceId}. The method a payment ran with is in the payment object's channel field.
  • Changing it: In the panel, from the device edit dialog, or with PATCH /api/v1/physical-pos/devices/{deviceId} (integrationChannel, physical_pos:manage scope). → Devices › Update a device

Lunixi sends the request according to the method in the record. The method in the record must match the method the device actually runs with; when you change it, make sure the setting on the device matches.

Methods and operations by device model

  • Some device models work with only one connection method at a time; the method changes with the device's own setting. Some models support several methods together.
  • Which method and which operations (sale, pre-authorisation, refund and so on) are supported depends on the device model. The capabilities summary in the device detail shows the operations defined for the device's registered method (operations) and refund support. Without a definition, capabilities.state is UNDEFINED and a payment gets 422 physical_pos.payment.operation_unsupported (capability_undefined).
  • On some models that support several methods, a given operation can be sent over the other path, fixed by the model's definition. This choice is set in advance; it does not change after an error.

If the app is closed or the device is offline

  1. Before sending the command, Lunixi checks on every request that the device is ready for payment. → Step 1
  2. If the device is not ready, the request gets 409 physical_pos.payment.device_offline or 503 physical_pos.presence.unavailable. No payment record is opened and the command is not queued.
  3. Lunixi does not resend the request over another path on its own (for example through the vendor's cloud service). This prevents the same payment from being charged twice over two paths.
  4. Check the device's status (presence.decision, presence.notReadyReason); when the device is ready, send the request again with the same Idempotency-Key and the same body. → Retries

If the connection drops after the command was sent to the device, the payment is not sent again; if no outcome arrives in time, the payment becomes UNKNOWN. → If the outcome is uncertain

Sales started on the device

When a cashier starts a sale directly on the device, no API request is made on your side. The sale is recorded with origin: "DEVICE_DIRECT"; you are notified with the physical_pos.payment.device_sale webhook and it appears in the transaction list. → Payment Flow › Sales made on the device

SoftPOS and direct connections

  • The catalog and device records have the value deviceType: "SOFTPOS" (a phone or tablet that accepts cards). A flow for accepting cards with SoftPOS is not available yet.
  • Your till software talking to the device directly over the local network or a cable (serial, USB) does not go through the Lunixi API. The flow on this page is the integration where you send the payment request to Lunixi.

Accepted by the device, but execution never began

An app can persist a command without ever calling the payment application, for example because preparation fails or its deadline expires. A supporting app permanently prevents any later execution of that command. Once Lunixi validates this record, the payment becomes EXPIRED with reason DEVICE_EXECUTION_INHIBITED. Continue using the normal payment query and webhook flow. This does not fabricate a bank decline or a card transaction result.

This closure does not apply to a timeout after dispatch to the payment application. An uncertain payment is queried; no new charge or automatic switch to another execution channel follows. Older clients without positive never-dispatched proof continue using query/review recovery. Compatible app and server releases are required; source delivery documented here does not verify a production deployment.

Pavo APP2APP source status — 8 November 2026

Sale/refund/void execution and read-only recovery are connected in the Android source. Having PavoPay installed does not prove response authenticity or actual sandbox mode. Launching and validating the financial result are separate checks; the app does not report readiness without an accepted producer build/channel/mode profile. Current support boundaries. An Intent error never automatically switches to LOCAL_REST or VENDOR_CLOUD.