Quickstart: First Payment
For invoice, buyer and fiscal-document fields, and the sale application registration awaiting release, see Sales data and support status. merchantReference does not provide an invoice number or fiscal validation.
- Base path
/api/v1/physical-pos- Identity
- Ed25519 request signature on every request —
X-Key-Id,X-Date,X-Nonce,X-Signature, plusDigeston requests with a body. ±5 min clock window, single-use nonce. A Bearer token or a panel session is not accepted here. - Authorization
- The key must carry the Physical POS product (
PHYSICAL_POS) and the scope for the endpoints on this page:physical_pos:payments·physical_pos:view. Without the product the call gets403 PRODUCT_NOT_ENABLED; without the scope403 API_INSUFFICIENT_SCOPE. See Authentication and Scopes. - Cross-surface
- These endpoints are the s2s surface — call them from your own server with a signed request. The same records have screens in the panel, but panel endpoints cannot be called with an API key, and these endpoints cannot be called with a panel session.
This guide takes you through starting a sale on a POS device in your store from your own server, end to end: you choose the device, start the payment, read the response and get the outcome. The card is read on the device; the API takes no card data.
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.
1. Choose the device GET /devices → presence.decision: READY
2. Start the payment POST /payments → 202 · paymentStatus: NOT_STARTED
3. Store the response paymentId, resultDeadlineAt
4. Get the outcome webhook physical_pos.payment.* or GET /payments/{paymentId}The payment state machine, reversals and end of day: Payment Flow. Every field and error code of the endpoints: Payment Operations.
Before you start
API key and scopes
| Requirement | Description |
|---|---|
Live API key (mk_live_…) | You start payments with a live key. A test key only reads payments; a start request gets 403 physical_pos.environment.test_key_read_only. → Environments |
| Physical POS product | Your key must have the PHYSICAL_POS product; otherwise 403 PRODUCT_NOT_ENABLED. |
physical_pos:payments scope | Starting, reversing and cancelling payments is possible only with this scope. It also reads payments, transactions and reports. |
physical_pos:view scope | Needed to read devices (Step 1). physical_pos:manage cannot make payments and does not include reads. |
| Request signature | Every request is signed with your API key; requests with a body also send the Digest header. → Authentication › Signing helper |
physical_pos:payments is not added to your existing keys automatically; select it in the key's permission settings in the panel. → Scopes
Payments cannot be started in the test environment. You can try reads, signing and scope errors with a test key; you start payments with a live key and a real device. Keep the live key on your server only.
Device and terminal
For a device to take payments it must be active, its ownership verified, linked to a logical terminal and connected to Lunixi and ready. The steps to prepare a device from scratch and the full list of conditions: Preparing a Device for Payments.
How your request reaches the device
The payment request is delivered, depending on the device record's connection method (integrationChannel), to the Lunixi app on the device or to the vendor's cloud service; you always send the same request. Methods, differences by device model and what happens when the device is offline: Connection Methods.
Step 1 — Choose the device
Choose the device you will start the payment on from the list. List rows carry a summary of the device's connection status (presence), so a single request shows which devices are ready for payment.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices?storeId=00000000-0000-0000-0000-000000000101&lifecycleStatus=ACTIVE&ownershipStatus=VERIFIED"
lunixi_sign GET "$REQ_PATH"
curl "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"Check these fields on each row of the response (the other fields of the row: Devices › Device object):
{
"id": "00000000-0000-0000-0000-000000000401",
"displayName": "Till 1 POS",
"lifecycleStatus": "ACTIVE",
"ownershipStatus": "VERIFIED",
"integrationChannel": "APP2APP",
"logicalTerminal": { "id": "00000000-0000-0000-0000-000000000301", "code": "IST-KADIKOY-01" },
"presence": {
"connectionState": "ONLINE",
"lastSeenAt": "2026-01-02T08:59:50.000Z",
"readyForPayment": true,
"notReadyReason": null,
"decision": "READY",
"source": "LIVE"
}
}presence.decision is the result the device readiness check will give when you start a payment:
presence.decision | Meaning | If you start a payment |
|---|---|---|
READY | The device is connected and ready to take a payment. | Passes the readiness check. |
NOT_READY_DEVICE | The device is not connected, has not sent a signal for a while, or one of the apps on the device is not ready. The reason is in presence.notReadyReason. | 409 physical_pos.payment.device_offline |
UNVERIFIABLE | Lunixi cannot verify the device's status at the moment; the cause is not on your device. | 503 physical_pos.presence.unavailable |
- The value set can grow; do not treat a value you do not recognise as
READY.presenceisnullwhen it could not be read. presencecovers only the connection and the apps on the device. The device's status, ownership and terminal link are checked separately against the conditions above.- You see why a device is not ready, and whether a payment is running on it (
presence.busy), in the device detail:GET /api/v1/physical-pos/devices/{deviceId}. → Devices › Connection status - This read is optional. Readiness is checked again on every payment request; the device can lose its connection between the read and the payment.
You use the device's id as target.deviceId in the payment. If you work with your own device identifiers, you can also target the device by the externalRef you gave when registering it: Target device.
Step 2 — Start the payment
Create and store an Idempotency-Key
Idempotency-Key is required on payment start and reversal requests. The key prevents a second payment from being opened for the same sale after a network error.
- Create a new UUID for every payment.
- Write the key to your own records together with your order before you send the request.
- Send the request with this key. Use the same key and the same body on every attempt of the same payment.
| Endpoint | Idempotency-Key |
|---|---|
POST /payments | Required |
POST /payments/{paymentId}/reversals | Required |
POST /payments/{paymentId}/cancel | Optional |
Format: 8–200 printable ASCII characters without spaces. A missing header gets 400 physical_pos.idempotency.key_required, a malformed one 400 physical_pos.idempotency.key_invalid.
| Situation | Result |
|---|---|
| New key | The payment is opened: 202, replayed: false. |
| Same key, same body | No new payment is opened; the payment is returned in its current state: 200, replayed: true. The response is not a copy of the first response; it shows the payment's state at that moment. |
| Same key, different body or another operation (e.g. a refund with a sale's key) | 409 physical_pos.idempotency_mismatch. |
- Bodies are compared after the field rules are applied; field order does not matter.
- On a reversal, the
paymentIdin the path is part of the comparison. - If the request was rejected by a field rule or a device or terminal check (e.g.
400,404,409 device_busy,409 device_offline,422), nothing is written; you can retry with the same key. - A key is kept for at least 7 days. After that, the same key opens a new payment: use a new UUID for every payment; do not reuse keys.
- The panel and your live API key share the same key space.
After a network error, retry with the same key. When you get a timeout, a dropped connection, a 5xx or 503 physical_pos.service.busy, repeat the request with the same Idempotency-Key and the same body: if the payment was opened, the existing payment comes back with replayed: true; if not, it is opened now. Retrying with a new key can open a second payment. → Retries
On the cancel endpoint the key is optional; repeating a cancellation is always safe. If you send a key, the same key on the same payment's cancellation returns the payment's current state with replayed: true; the same key on another payment or another operation gets 409 physical_pos.idempotency_mismatch.
Send the request
POST /api/v1/physical-pos/payments · Idempotency-Key required
The request below starts a single (non-instalment) sale of 45.00 TRY on the device:
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
IDEMPOTENCY_KEY="7b0c6a1e-2f8d-4c55-9a51-3f0e8d1c2a90" # store it with your order first
BODY='{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"4500","currency":"TRY","merchantReference":"ORD-2026-000123"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data-raw "$BODY"- The cURL example computes the signature with
lunixi-sign.sh. Send the body as compact JSON without spaces;Digestis computed from this text. → Signing helper - The SDKs sign the request, repeat an uncertain attempt with the same key and the same body, and throw
PhysicalPosOutcomeUnknownError(PHP:PhysicalPosOutcomeUnknownException) if the outcome is still uncertain. They reject a field that looks like card data before anything is sent. → Node.js SDK · PHP SDK - The amount is always a string in the minor unit:
"4500"= 45.00 TRY. A JSON number (4500) is rejected. → Payment Flow › Amounts
Fields
| Field | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | SALE (sale). Other values: PREAUTH_OPEN (pre-authorisation) and REFUND_UNMATCHED (unmatched refund). |
target | object | Yes | The target device; exactly one of the forms below. → Target device |
amountMinor | string | Yes | Amount in the minor unit (kuruş for TRY); a canonical positive integer string such as "4500". |
currency | string | Yes | ISO 4217 code (TRY). The device and the bank row must support this currency. |
merchantReference | string | null | No, recommended | Your own order or receipt number: printable ASCII without spaces, at most 128 characters. A second safeguard against charging the same sale twice. → merchantReference |
installmentCount | integer | null | No | Number of instalments, 2–36; SALE only. Not sent, null or 0 means a single payment. The device model's limit applies. |
startTimeoutSeconds | integer | No | Time for the payment to start on the device, 5–30 seconds. Not sent or 0 means 30. If the device model's limit is shorter, that limit applies. |
terminalAcquirerId | string (UUID) | null | No | The bank row the payment goes through. If not sent, the device chooses the bank. → Bank row |
items | array | No | Sale items; SALE only. → Sale with items |
allowDuplicateReference | boolean | No | When true, the duplicate reference checks are skipped. Default false. → Warning |
instrument | string | No | Payment instrument; only CARD is valid for a payment started from the API. CARD when not sent. |
- An undeclared field in the body gets
400 VALIDATION_ERROR.organizationId,merchantIdandenvironmentare not sent; your signed key decides the organization and the environment. - The rules and error codes of every field: Payments › Starting a payment.
Target device
| Form | When |
|---|---|
{ "deviceId": "…" } | Recommended. The id from the device list. |
{ "externalRef": "…" } | When you gave your own identifier as externalRef while registering the device. |
{ "vendorCode": "…", "serialNumber": "…" } | When you know the device by its vendor code and serial number; the two fields are sent together. |
No target or more than one target gets 400 physical_pos.payment.target_invalid (details.reason: none or multiple). A device that is not found, belongs to another organization or the other environment, or is retired gets the same answer: 404 physical_pos.device.not_found. Targeting by store, register or terminal id is not possible. → Payments › Target device
merchantReference and a new sale with the same reference
merchantReference is the order or receipt number in your own system. When you start a new sale (SALE) with the same reference, two checks are made:
| Situation | Result |
|---|---|
A sale with the same reference and an outcome not yet final (NOT_STARTED, IN_PROGRESS, UNKNOWN, MANUAL_REVIEW) exists within the last 30 days | 409 physical_pos.payment.previous_outcome_unknown, details.previousPaymentId |
An APPROVED sale with the same reference exists within a short time (10 minutes by default) | 409 physical_pos.payment.duplicate_reference_recent, details.previousPaymentId |
- The check runs across devices: a sale started with the same reference on another device is caught too.
allowDuplicateReference: trueskips both checks. Use it only when you deliberately take a second payment with the same reference.- The rule does not apply to reversals or other operations.
- You can read the earlier payment with
details.previousPaymentIdor find it with themerchantReferencefilter of the list.
Always use the same merchantReference for the same sale. Do not change the reference across the attempts of one sale (a retry after a network error, restarting while the device is busy); the check only works this way.
Do not use allowDuplicateReference when you get previous_outcome_unknown. The earlier payment's outcome is not known and money may have been taken; wait for the earlier payment's outcome.
No card data
The card is read on the device; the API does not take card numbers, expiry dates, security codes or magnetic stripe data.
- If the body or the query string contains a field name that looks like card data (such as
pan,cardNumber,cvv,expiry,track2), the request gets400 physical_pos.payment.card_data_rejected. - A value that looks like a card number in a free-text field (
merchantReference, the item nameitems[].name,items[].taxGroupCode) gets the same code. details.fieldgives only the path of the field (e.g.items[1].name); the value you sent is not written to the response, records or webhooks.- A 13- or 14-digit barcode with a valid check digit in an item name is not treated as a card number. → Items › Barcode
In responses, card details appear only as the masked number (cardMasked: first 6 and last 4 digits, or the last 4 digits only), the card brand and the entry mode.
Sale with items
To start a sale with product lines, send the items array. Items come back with their tax breakdown when the payment is read, and they allow item-based refunds.
{
"operation": "SALE",
"target": { "deviceId": "00000000-0000-0000-0000-000000000401" },
"amountMinor": "4500",
"currency": "TRY",
"merchantReference": "ORD-2026-000124",
"items": [
{ "lineNo": 1, "name": "Tea", "quantityMilli": 2000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV10", "lineTotalMinor": "3000", "barcode": "8690000000005" },
{ "lineNo": 2, "name": "Simit", "quantityMilli": 1000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV1", "lineTotalMinor": "1500" }
]
}- Send items only on
SALE; at most 500 lines. For a sale without items, do not send the field at all; an empty array is rejected. lineNostarts at 1 and increases without gaps.quantityMilliis quantity × 1000: 1 piece =1000, 1.5 kg =1500.unitPriceMinoris the unit price including all taxes. You do not send tax amounts; tax is calculated fromtaxGroupCode.lineTotalMinor=quantityMilli × unitPriceMinor / 1000, rounded half up, and must match exactly.- The sum of the lines'
lineTotalMinormust equalamountMinor.
If a rule is broken the request gets 400 physical_pos.fiscal_document.items_invalid; details.field gives the dotted path of the field (such as items.0.quantityMilli) and details.reason the reason. An unknown tax group gets 422 physical_pos.fiscal_document.unsupported (tax_group_unsupported). Tax groups, unit codes and the item view: Items and Item Refunds.
Step 3 — Understand the response
The response says the payment was accepted, not that it was paid. The card has not been read yet; the outcome arrives asynchronously.
| HTTP | data.replayed | Meaning |
|---|---|---|
202 Accepted | false | A new payment was opened; paymentStatus: "NOT_STARTED". The command is sent to the device. |
200 OK | true | This body was already sent with this key; no new payment was opened. The payment comes back in its current state: the status may be other than NOT_STARTED, e.g. APPROVED. |
{
"status": "success",
"code": "SUCCESS",
"data": {
"payment": {
"paymentId": "01900000-0000-7000-8000-000000000501",
"rootPaymentId": "01900000-0000-7000-8000-000000000501",
"originalPaymentId": null,
"origin": "API",
"operation": "SALE",
"paymentStatus": "NOT_STARTED",
"statusReason": null,
"outcomeConflict": false,
"resolvable": false,
"deviceId": "00000000-0000-0000-0000-000000000401",
"logicalTerminalId": "00000000-0000-0000-0000-000000000301",
"terminalAcquirerId": null,
"channel": "APP2APP",
"vendorReference": "01900000000070008000000000000501",
"amountMinor": "4500",
"approvedAmountMinor": null,
"currency": "TRY",
"installmentCount": null,
"instrument": "CARD",
"merchantReference": "ORD-2026-000123",
"reversedMinor": "0",
"capturedMinor": "0",
"reversalReservedMinor": "0",
"pendingReversalId": null,
"reversalStatus": "NONE",
"expiresAt": "2026-01-02T09:00:30.000Z",
"resultDeadlineAt": "2026-01-02T09:03:30.000Z",
"completedAt": null,
"settledAt": null,
"settlementBatchNo": null,
"createdAt": "2026-01-02T09:00:00.000Z",
"updatedAt": "2026-01-02T09:00:00.000Z",
"rowVersion": 2,
"historySeq": 1,
"tender": {
"tenderStatus": "PENDING",
"cardMasked": null,
"cardBrand": null,
"entryMode": null,
"acquirerCode": null,
"authCode": null,
"rrn": null
},
"items": [],
"refundItems": []
},
"replayed": false
},
"statusCode": 202,
"requestId": "00000000-0000-0000-0000-000000000000"
}Fields to store at this step:
| Field | Why |
|---|---|
paymentId | To read the payment, match the webhook to your order, and for cancellation and reversals. |
paymentStatus | Where the payment stands in terms of money; base your decisions on this field only. |
expiresAt | The last moment for the payment to start on the device. If it does not start in time, the payment becomes EXPIRED. |
resultDeadlineAt | The last moment the outcome is expected. If no outcome arrives, the payment becomes UNKNOWN. |
historySeq | To check the order of webhooks. → Ordering and duplicates |
Even for a sale with items, items is an empty array in the start response; you read the items with GET /payments/{paymentId}. Every field of the payment object: Payments › Payment object.
Statuses. The payment goes from NOT_STARTED through IN_PROGRESS (the device is waiting for the card or the bank's answer) to one of its final statuses:
| Final status | Money |
|---|---|
APPROVED | Taken. |
PARTIALLY_APPROVED | Less than requested was taken; the amount taken is approvedAmountMinor. |
DECLINED, CANCELLED, EXPIRED, FAILED | Not taken. |
UNKNOWN and MANUAL_REVIEW are not final statuses: money may have been taken. → If the outcome is uncertain. All statuses and statusReason values: Payment Flow › Payment statuses.
Step 4 — Get the outcome
By webhook (recommended)
- In the panel, on the Webhooks page, create an endpoint for the Physical POS product and subscribe it to the
physical_pos.*events. → Webhook Setup - Verify the delivery's signature over the raw body, before parsing it. → Webhook Events › Signature verification
- Match the event to your payment with
data.paymentIdand to your order withdata.merchantReference. - Update the order according to
data.paymentStatus:
| Event | What to do |
|---|---|
physical_pos.payment.approved | Complete the sale. A partial approval arrives as partially_approved; the amount taken is approvedAmountMinor. |
physical_pos.payment.declined, .cancelled, .expired, .failed | No money was taken. To take the payment with another card, you can start a new payment (new Idempotency-Key). |
physical_pos.payment.unknown, .manual_review | Do not charge again. → If the outcome is uncertain |
- No webhook is sent when the payment is started or starts on the device (
NOT_STARTED,IN_PROGRESS). - The same event can arrive more than once; deduplicate with
id. Order is not guaranteed; ignore an event whosedata.historySeqis lower than the one you have. - The webhook does not carry the bank's authorisation code, the RRN or the items; read the payment for these.
The event list and payload fields: Webhook Events.
By polling
If you cannot receive webhooks, or you doubt a webhook, read the payment:
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501"
lunixi_sign GET "$REQ_PATH"
curl "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"Node: await lunixi.physicalPos.getPayment(paymentId) · PHP: $lunixi->physicalPos()->getPayment($paymentId) · Python: lunixi.physical_pos().get_payment(payment_id) · Java: lunixi.physicalPos().getPayment(paymentId)
- Read at short intervals (e.g. every 2 seconds) until the payment reaches a final status. Payment reads are not rate limited.
- The outcome is expected until
resultDeadlineAt. If no outcome has arrived by then, the payment becomesUNKNOWN; keep reading less often. - A timeout is not a failure: a payment whose outcome deadline passes becomes
UNKNOWN, notDECLINED.
Timings
| Timing | Value |
|---|---|
Start time (expiresAt) | startTimeoutSeconds: 5–30 seconds, default 30. 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. |
| Uncertain outcome hold | 10 minutes by default; the device takes no new payment during it. |
All timings: Payment Flow › Timings.
If the outcome is uncertain
NEVER start a new payment for the same sale with a new Idempotency-Key. While the outcome is uncertain, money may have been taken; a new key can charge your customer twice. Lunixi never charges an uncertain payment again automatically.
| Situation | What to do |
|---|---|
You got no answer to the start request (timeout, dropped connection, 5xx) or the SDK threw PhysicalPosOutcomeUnknownError / PhysicalPosOutcomeUnknownException | Repeat the request with the same Idempotency-Key and the same body. If the payment was opened, its current state comes back with 200, replayed: true; if not, it is opened now. You can also find the payment with GET /payments?merchantReference=…. |
The payment is UNKNOWN (physical_pos.payment.unknown) | Wait. The outcome is verified automatically; once settled, the payment moves to its final status and a webhook is sent. During this time (10 minutes by default) the device takes no new payment: 409 physical_pos.payment.device_busy (unknown_outcome_hold). |
The payment is MANUAL_REVIEW (physical_pos.payment.manual_review) | Resolve the payment in the panel with evidence (such as a bank statement, an end-of-day report or the device receipt). There is no API endpoint for this. The device can take payments again. |
A new sale with the same reference got 409 physical_pos.payment.previous_outcome_unknown | The earlier payment (details.previousPaymentId) is not settled. Wait for its outcome; do not send allowDuplicateReference: true. |
- An uncertain payment cannot be cancelled (
409 physical_pos.payment.not_cancellable,outcome_unknown) or reversed (409 physical_pos.payment.not_reversible,root_not_approved). - The list of your uncertain payments: Transactions › Uncertain payments. The flow in detail: Payment Flow › Uncertain outcome.
Retries
| Error | What to do |
|---|---|
409 physical_pos.payment.device_busy, 409 physical_pos.payment.device_not_payable (pairing_hold) | Wait details.retryAfterSeconds and retry with the same Idempotency-Key. |
409 physical_pos.payment.device_offline | Start it again when the device is ready for payment; the payment is not queued. No record was opened, so you can use the same Idempotency-Key. → Device readiness |
503 physical_pos.presence.unavailable | The device's status cannot be verified at the moment. Retry with the same Idempotency-Key, with backoff and a limited number of attempts (e.g. at most 5, waiting 1, 2, 4 and 8 seconds); if it persists, contact support. |
503 physical_pos.signing.unavailable, 503 physical_pos.service.busy, 503 physical_pos.service.clock_skew, other 5xx and timeouts | Retry with the same Idempotency-Key, with backoff and a limited number of attempts (e.g. at most 5, waiting 1, 2, 4 and 8 seconds); if it persists, contact support. |
Other 4xx errors are not fixed by retrying; fix the request.
Rate limits
Payment writes (start, reverse and cancel) are limited to 120 requests per 60 seconds per organization and API key; the three endpoints share one counter. Payment reads, transactions, reports and end-of-day records are not limited.
Over the limit the request gets 429 RATE_LIMITED; the Retry-After header and details.retryAfterSeconds give the seconds to wait. Limits of the management endpoints: Common Rules › Rate limits.
Common errors and fixes
| Error | Cause | Fix |
|---|---|---|
400 physical_pos.payment.card_data_rejected | A field name that looks like card data in the body, or a value that looks like a card number in free text. | Remove or fix the field in details.field. → Card data |
400 physical_pos.payment.amount_invalid | The amount is a JSON number, zero or a non-canonical string. | Send the amount as a string such as "4500". |
400 physical_pos.payment.target_invalid · 400 physical_pos.fiscal_document.items_invalid | A nested field (target.*, items.N.*) is missing, has the wrong type or breaks a rule. | details.field gives the dotted path (such as items.0.quantityMilli), details.reason the reason. The response returns the first error; fix it and send again. |
400 physical_pos.idempotency.key_required | No Idempotency-Key header. | Send a new UUID for every payment. → Idempotency-Key |
403 physical_pos.environment.test_key_read_only | The payment was started with a test key. | Use a live key. |
409 physical_pos.payment.device_offline | The device is not ready for payment (presence.decision: "NOT_READY_DEVICE"). | Check that the device is on, connected to the network and that the Lunixi app is running; the reason is in presence.notReadyReason. → Step 1 |
503 physical_pos.presence.unavailable | The device's status cannot be verified at the moment (UNVERIFIABLE); the cause is not on your device. | Retry with the same key, with backoff. → Retries |
409 physical_pos.payment.device_busy | A payment, an uncertain outcome hold or an end-of-day is running on the device. | Retry with the same key after details.retryAfterSeconds. |
409 physical_pos.payment.device_not_payable · 409 physical_pos.payment.terminal_not_payable | The device or the terminal is not active or not verified, or the device is not linked to a terminal. | Check details.reason. → Device and terminal |
422 physical_pos.payment.operation_unsupported | capability_undefined: no payment capability definition for the device model. channel_unset: no communication channel is set. | Check details.reason; no payment record is created. |
409 physical_pos.payment.previous_outcome_unknown | An earlier sale with the same reference is not settled. | Wait for the earlier payment's outcome; do not use allowDuplicateReference. |
409 physical_pos.idempotency_mismatch | The key was used with another body or operation. | Do not change the body when repeating the same payment; use a new key for a new payment. |
429 RATE_LIMITED | More than 120 payment writes in 60 seconds. | Wait Retry-After. → Rate limits |
All codes: Error Codes.
Next steps
- Cancel a payment before its command reaches the device: Payments › Cancel
- Void or refund an approved payment: Payments › Reversal
- Item-based refund: Items › Item refund
- List payments with their reversals: Transactions
- End of day and the void rule: Payment Flow › End of day and voids · End-of-Day Records
- Sales and tax summaries: Reports