Payment Flow
With Physical POS you start the payment from your own server; the card is read on the POS device in your store. Lunixi signs the payment command and sends it to the device, records the outcome that comes back from the device and notifies you of the outcome by webhook. This page describes the payment lifecycle: statuses, reversals, uncertain outcomes and end of day.
- To start a payment step by step: Start a Payment
- Endpoint fields and error codes: Payment Operations
Flow
- Accepted: The start request is accepted with
202 Acceptedand the payment is opened inNOT_STARTED. This response means "the payment was accepted", not "it was paid". - On the device: When the device starts the payment, the payment becomes
IN_PROGRESS: the device is waiting for the card or the bank's answer. - Outcome: When the outcome arrives, the payment moves to one of its final statuses and a
physical_pos.payment.*webhook is sent. → Webhook Events - Following: You follow the outcome by webhook or by reading the payment. → Start a Payment › Get the outcome
Reversals such as void, refund and pre-authorisation close follow the same flow: each reversal opens a new payment record linked to the original payment (a child payment) and gets its own outcome.
Starting a payment or a reversal runs when a payment capability definition exists for the target device's model. On a device without a capability definition the request gets 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) once the device is found and its terminal link and communication channel are checked; no payment record is created.
Payment statuses
APPROVED and PARTIALLY_APPROVED. UNKNOWN is not a failure: the money may have been taken, so do not start the payment again.paymentStatus tells you where the payment stands in terms of money. Base your decisions on this field only.
| Status | Meaning | Final? |
|---|---|---|
NOT_STARTED | The payment record was opened; the device has not started the payment yet. | No |
IN_PROGRESS | The device started the payment; waiting for the card or the bank's answer. | No |
APPROVED | Money was taken. On a reversal: the void, refund or close went through. | Yes |
PARTIALLY_APPROVED | Money was taken, but less than requested; the amount taken is approvedAmountMinor. | Yes |
DECLINED | The bank or the card declined; no money was taken. | Yes |
CANCELLED | The payment had started on the device and was cancelled; no money was taken. | Yes |
EXPIRED | The payment never started on the device: the time ran out or you cancelled before the command reached the device. No money was taken. | Yes |
FAILED | The payment never started on the device: the device rejected the command. No money was taken. | Yes |
UNKNOWN | The outcome is unknown; money may have been taken. The outcome is being verified automatically. → Uncertain outcome | No |
MANUAL_REVIEW | Automatic verification did not settle the outcome; the payment is resolved in the panel. → Uncertain outcome | No |
- A payment in a final status does not change status. If evidence of a different outcome arrives later, the status is kept, the payment gets
outcomeConflict: trueand no webhook is sent for that evidence. When you seeoutcomeConflict: true, review the payment in the panel. - A timeout is not a failure. If no outcome arrives by
resultDeadlineAt, the payment becomesUNKNOWN, notDECLINED.
Reversal status: reversalStatus
Shows the combined effect of reversals on the original payment (the root):
| Value | Meaning |
|---|---|
NONE | No reversal. |
PARTIALLY_REFUNDED | Partly refunded; further refunds are possible. |
REFUNDED | Fully refunded. |
VOIDED | Voided. |
PREAUTH_CLOSED | Pre-authorisation closed (the amount was captured). |
PREAUTH_CANCELLED | Pre-authorisation cancelled. |
PREAUTH_EXPIRED | Pre-authorisation expired. |
No further reversal is possible on a payment in VOIDED, REFUNDED, PREAUTH_CANCELLED or PREAUTH_EXPIRED. When a reversal completes, no separate webhook is sent for the original payment; read its current reversalStatus with GET /payments/{paymentId}.
Card outcome: tender.tenderStatus
PENDING, APPROVED, PARTIALLY_APPROVED, DECLINED, CANCELLED or UNKNOWN. On a payment that was cancelled, expired or never started on the device, tenderStatus can stay PENDING; use paymentStatus for the payment's outcome.
Status reason: statusReason
statusReason is the machine-readable reason of the last transition. The value set is open and new values can be added: ignore values you do not recognise and base your decision on paymentStatus. Values that may need action:
| Value | Meaning |
|---|---|
MERCHANT_CANCELLED_BEFORE_DISPATCH | You cancelled the payment before the command reached the device (EXPIRED). |
COMMAND_EXPIRED_BEFORE_DISPATCH | The start time ran out before the command reached the device (EXPIRED). Check that the device is ready for payment and start a new payment. → Device readiness |
COMMAND_DELIVERY_UNKNOWN | It could not be confirmed whether the command reached the device (UNKNOWN). Do not start the payment again. |
RESULT_DEADLINE_PASSED | The outcome did not arrive in time (UNKNOWN). Do not start the payment again. |
UNKNOWN_HOLD_EXPIRED | The outcome was not settled during the hold; the payment moved to review (MANUAL_REVIEW). |
DEVICE_REJECTED_<code> | The device rejected the command (FAILED). E.g. DEVICE_REJECTED_ORIGINAL_NOT_FOUND: the device could not find the original transaction of a reversal. |
MERCHANT_RESOLVED_<status>, MERCHANT_RESOLVED_NOT_CHARGED | The payment was resolved with evidence in the panel. |
PROVIDER_CODE_EXPIRED | The meal card code expired and no payment was made (EXPIRED). |
PROVIDER_CODE_WINDOW_ELAPSED | The meal card payment's outcome did not become definite within the query period (UNKNOWN). Do not restart the payment. |
VENDOR_RESULT_<status> | The outcome came from the device vendor's cloud. <status>: APPROVED, PARTIALLY_APPROVED, DECLINED or CANCELLED. |
VENDOR_REJECTED | The device vendor's cloud rejected the payment request (FAILED). |
VENDOR_SUBMIT_INDETERMINATE, VENDOR_RESULT_INVALID | Whether the request reached the vendor's cloud, or its outcome, could not be verified (UNKNOWN). Do not restart the payment. |
Uncertain outcome: UNKNOWN and MANUAL_REVIEW
Do not start a payment with an uncertain outcome again. In UNKNOWN, money may have been taken. Lunixi never charges an uncertain payment again automatically. If you start a new payment for the same sale, your customer may end up paying twice.
- When a payment becomes
UNKNOWN, aphysical_pos.payment.unknownwebhook is sent. It means "do not charge again, the outcome is being verified". - During this time (10 minutes by default) the device does not take a new payment: a payment started on the same device gets
409 physical_pos.payment.device_busy(details.reason:unknown_outcome_hold,details.retryAfterSeconds). - If the outcome is settled in this time, the payment moves to its final status and the matching webhook is sent.
- If not, the payment becomes
MANUAL_REVIEW, aphysical_pos.payment.manual_reviewwebhook is sent and the device can take payments again. The outcome keeps being queried in the background for up to 7 days. - You resolve a
MANUAL_REVIEWpayment in the panel with evidence: a bank statement, the vendor portal, an end-of-day report, the device receipt or other evidence with a note. A "money was taken" decision needs the bank's authorisation code or RRN. When the payment showsresolvable: true, it can be resolved in the panel. There is no API endpoint for this. - A payment resolved in the panel moves to its final status; its webhook payload carries
resolvedBy: "MERCHANT".
On an uncertain payment, cancellation gets 409 physical_pos.payment.not_cancellable (details.reason: outcome_unknown) and a reversal gets 409 physical_pos.payment.not_reversible (details.reason: root_not_approved). The list of your uncertain payments: Transactions › Uncertain payments.
End of day and voids
A payment whose end of day has been taken cannot be voided; refund the amount to the same payment instead. Details and which reversal to use when: End of Day, Void and Refund.
Sales made on the device
A sale can also be made directly on the device, without being started from Lunixi. Such a sale is recorded with origin: "DEVICE_DIRECT" and is created already approved.
- When the sale is recorded, the
physical_pos.payment.device_salewebhook is sent. → Webhook Events › Sales made on the device - You can also read the sale from the payment and transaction endpoints. → Transactions
- The sale can only be refunded; it cannot be voided. The refund runs only on the device the sale was made on. → Payments › Refunding a sale made on the device
One active payment per device
A device runs one payment at a time. A payment in NOT_STARTED, IN_PROGRESS or UNKNOWN holds the device; MANUAL_REVIEW releases it. A payment started on a busy device gets 409 physical_pos.payment.device_busy:
details.reason | Meaning |
|---|---|
payment_in_progress | A payment is running on the device. |
unknown_outcome_hold | A payment on the device has an uncertain outcome; the device is held for a while. |
settlement_in_progress | An end-of-day is running on the device. |
Wait details.retryAfterSeconds and retry. No payment record was opened, so you can retry with the same Idempotency-Key.
Device readiness
Payment and reversal commands are sent only to a device that is ready for payment; commands are not queued. On every request Lunixi checks, one by one, that the device is connected, that its signals arrive on time, that the Lunixi app on the device is healthy and that the payment app can be reached. An open connection alone is not enough.
| Error | Meaning | What to do |
|---|---|---|
409 physical_pos.payment.device_offline | The device is not connected, has not sent a signal for a while, or one of the apps on the device is not ready. | Check in the store that the device is on and connected to the network and that the Lunixi app is running; send the request again once the device is ready. No record was opened, so you can use the same Idempotency-Key. |
503 physical_pos.presence.unavailable | Lunixi cannot verify the device's status at that moment; the cause is not on your device. | Retry with the same Idempotency-Key, with backoff and a limited number of attempts; if it persists, contact support. |
Both errors carry details.retryable: true; the reason is not in the response. You see the device's status in the device list and the device detail (GET /devices/{deviceId}): presence.decision gives the result a payment start will get (READY, NOT_READY_DEVICE → 409 device_offline, UNVERIFIABLE → 503 presence.unavailable) and presence.notReadyReason why the device is not ready. → Devices › Connection status · Start a Payment › Choose the device
You do not need to read the device before starting a payment; readiness is checked again on every request. If another payment is running on the device, a separate error comes back: One active payment per device.
Start rules
The rules for starting payments and reversals safely are on the Start a Payment page:
| Rule | Summary |
|---|---|
| Idempotency-Key | Required on start and reversal. A new UUID for every payment; after a network error, repeat with the same key and the same body. |
| A new sale with the same reference | A new sale gets 409 while a sale with the same merchantReference has an outcome not yet final or was approved shortly before. |
| No card data | The card is read on the device; a field that looks like card data gets 400 physical_pos.payment.card_data_rejected. |
| Retries | Which errors to retry, how long to wait, and with the same key. |
| Rate limits | Payment writes: at most 120 requests per 60 seconds per organization and API key. |
Timings
| Timing | Value |
|---|---|
Start time (expiresAt) | startTimeoutSeconds: 5–30 seconds, default 30. If the device model's limit is shorter, that limit applies. If the payment does not start on the device in this time, it becomes EXPIRED. |
Outcome deadline (resultDeadlineAt) | At most 180 seconds after expiresAt; can be shorter depending on the device model. The exact moment is in the payment's resultDeadlineAt field. If no outcome arrives, the payment becomes UNKNOWN. |
| Uncertain outcome hold | 10 minutes by default; the device takes no new payment during it. Then the payment becomes MANUAL_REVIEW. |
| Background query of a payment under review | Up to 7 days. |
Idempotency-Key retention | At least 7 days. |
| Duplicate reference check | Sale with an outcome not yet final: 30 days; approved sale: 10 minutes by default. |
| List time window | Last 31 days by default, at most 93 days. |
| Webhook delivery | 10 seconds per request; 12 attempts over about 52 hours. → Webhooks |
Amounts
- All monetary API request, response and webhook fields use canonical base-10 integer strings in the currency's minor unit:
"4500"= 45.00 TRY. This includes item prices, taxes, reversal amounts, report totals and end-of-day differences. - Positive payment amounts use strings such as
"1"or"4500"; nonnegative totals can use"0", and signed net/difference fields can use"-4500". JSON numbers, decimal text, whitespace, a leading plus, leading zeroes and exponent notation are rejected. - Convert decimal input using the actual currency exponent: JPY
"45"→"45", TRY"45.00"→"4500", KWD"45.000"→"45000". These conversion examples do not imply that every device or bank supports those currencies; their capability and amount limits still apply. - Keep money as strings during transport and use an exact integer/decimal type for arithmetic. Do not pass it through
NumberorparseFloat. Counts,quantityMilli,rateBpandrowVersionremain JSON integers. - Sign the exact request body and verify webhook signatures over the original raw bytes before parsing or converting any fields. See the money contract and 1.0 migration.
Next steps
- Start a payment step by step: Start a Payment
- Endpoints, fields and examples: Payment Operations
- Sales with items and item refunds: Sale Items · Itemized Refund
- Outcome notifications: Webhook Events