Physical POS
Payment Flow

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.

Flow

Payment start sequenceYour server starts the payment and gets 202; Lunixi sends a signed command to the device; the device reads the card, gets an authorisation from the bank and reports the result to Lunixi; Lunixi sends the result to your server by webhook.POST /payments202 NOT_STARTEDSIGNED COMMANDCARDAPPROVE / DECLINERESULTWEBHOOKYour serverLunixiPOS deviceBank202 means "accepted", not "paid".
Dashed lines are responses. Get the outcome by webhook; if you do not want to wait, retrieve the payment.
  • Accepted: The start request is accepted with 202 Accepted and the payment is opened in NOT_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

Payment lifecycleA payment opens as NOT_STARTED, becomes IN_PROGRESS on the device and reaches a final status by approval, decline or cancellation; if it never starts it becomes EXPIRED or FAILED; without a result it becomes UNKNOWN, moves to a final status when evidence arrives, otherwise becomes MANUAL_REVIEW and is resolved in the panel.FINAL STATUSSTARTEDOKDECLINEDNOT STARTEDNO RESULT~10 MINIF EVIDENCEPANELNOT_STARTED202 · openedIN_PROGRESSdevice startedAPPROVED ·PARTIALLY_APPROVEDDECLINED ·CANCELLEDEXPIRED · FAILEDnever startedUNKNOWNmoney may be takenMANUAL_REVIEWresolved in panelLEGENDRUNNINGWATCHFINALYOU RESOLVE
Money has been taken only in 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.

StatusMeaningFinal?
NOT_STARTEDThe payment record was opened; the device has not started the payment yet.No
IN_PROGRESSThe device started the payment; waiting for the card or the bank's answer.No
APPROVEDMoney was taken. On a reversal: the void, refund or close went through.Yes
PARTIALLY_APPROVEDMoney was taken, but less than requested; the amount taken is approvedAmountMinor.Yes
DECLINEDThe bank or the card declined; no money was taken.Yes
CANCELLEDThe payment had started on the device and was cancelled; no money was taken.Yes
EXPIREDThe payment never started on the device: the time ran out or you cancelled before the command reached the device. No money was taken.Yes
FAILEDThe payment never started on the device: the device rejected the command. No money was taken.Yes
UNKNOWNThe outcome is unknown; money may have been taken. The outcome is being verified automatically. → Uncertain outcomeNo
MANUAL_REVIEWAutomatic verification did not settle the outcome; the payment is resolved in the panel. → Uncertain outcomeNo
  • 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: true and no webhook is sent for that evidence. When you see outcomeConflict: true, review the payment in the panel.
  • A timeout is not a failure. If no outcome arrives by resultDeadlineAt, the payment becomes UNKNOWN, not DECLINED.

Reversal status: reversalStatus

Shows the combined effect of reversals on the original payment (the root):

ValueMeaning
NONENo reversal.
PARTIALLY_REFUNDEDPartly refunded; further refunds are possible.
REFUNDEDFully refunded.
VOIDEDVoided.
PREAUTH_CLOSEDPre-authorisation closed (the amount was captured).
PREAUTH_CANCELLEDPre-authorisation cancelled.
PREAUTH_EXPIREDPre-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:

ValueMeaning
MERCHANT_CANCELLED_BEFORE_DISPATCHYou cancelled the payment before the command reached the device (EXPIRED).
COMMAND_EXPIRED_BEFORE_DISPATCHThe 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_UNKNOWNIt could not be confirmed whether the command reached the device (UNKNOWN). Do not start the payment again.
RESULT_DEADLINE_PASSEDThe outcome did not arrive in time (UNKNOWN). Do not start the payment again.
UNKNOWN_HOLD_EXPIREDThe 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_CHARGEDThe payment was resolved with evidence in the panel.
PROVIDER_CODE_EXPIREDThe meal card code expired and no payment was made (EXPIRED).
PROVIDER_CODE_WINDOW_ELAPSEDThe 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_REJECTEDThe device vendor's cloud rejected the payment request (FAILED).
VENDOR_SUBMIT_INDETERMINATE, VENDOR_RESULT_INVALIDWhether 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.

  1. When a payment becomes UNKNOWN, a physical_pos.payment.unknown webhook is sent. It means "do not charge again, the outcome is being verified".
  2. 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).
  3. If the outcome is settled in this time, the payment moves to its final status and the matching webhook is sent.
  4. If not, the payment becomes MANUAL_REVIEW, a physical_pos.payment.manual_review webhook is sent and the device can take payments again. The outcome keeps being queried in the background for up to 7 days.
  5. You resolve a MANUAL_REVIEW payment 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 shows resolvable: true, it can be resolved in the panel. There is no API endpoint for this.
  6. 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.

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.reasonMeaning
payment_in_progressA payment is running on the device.
unknown_outcome_holdA payment on the device has an uncertain outcome; the device is held for a while.
settlement_in_progressAn 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.

ErrorMeaningWhat to do
409 physical_pos.payment.device_offlineThe 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.unavailableLunixi 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:

RuleSummary
Idempotency-KeyRequired 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 referenceA new sale gets 409 while a sale with the same merchantReference has an outcome not yet final or was approved shortly before.
No card dataThe card is read on the device; a field that looks like card data gets 400 physical_pos.payment.card_data_rejected.
RetriesWhich errors to retry, how long to wait, and with the same key.
Rate limitsPayment writes: at most 120 requests per 60 seconds per organization and API key.

Timings

TimingValue
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 hold10 minutes by default; the device takes no new payment during it. Then the payment becomes MANUAL_REVIEW.
Background query of a payment under reviewUp to 7 days.
Idempotency-Key retentionAt least 7 days.
Duplicate reference checkSale with an outcome not yet final: 30 days; approved sale: 10 minutes by default.
List time windowLast 31 days by default, at most 93 days.
Webhook delivery10 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 Number or parseFloat. Counts, quantityMilli, rateBp and rowVersion remain 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