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
integrationChannel | What the device needs | How Lunixi delivers the request | When it fits |
|---|---|---|---|
APP2APP | The 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_REST | The 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_CLOUD | No 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
integrationChannelfield when you register the device (in the panel or withPOST /api/v1/physical-pos/devices). → Devices › Register a device - Seeing it: In the panel, on the device detail; in the API, in the
integrationChannelfield of the device list and ofGET /api/v1/physical-pos/devices/{deviceId}. The method a payment ran with is in the payment object'schannelfield. - Changing it: In the panel, from the device edit dialog, or with
PATCH /api/v1/physical-pos/devices/{deviceId}(integrationChannel,physical_pos:managescope). → 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
capabilitiessummary in the device detail shows the operations defined for the device's registered method (operations) and refund support. Without a definition,capabilities.stateisUNDEFINEDand a payment gets422 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
- Before sending the command, Lunixi checks on every request that the device is ready for payment. → Step 1
- If the device is not ready, the request gets
409 physical_pos.payment.device_offlineor503 physical_pos.presence.unavailable. No payment record is opened and the command is not queued. - 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.
- Check the device's status (
presence.decision,presence.notReadyReason); when the device is ready, send the request again with the sameIdempotency-Keyand 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.