Physical POS
Payment Operations
Uncertain Outcome

Uncertain Outcome

Who calls these endpoints?External API (s2s)
Base path
/api/v1/physical-pos
Identity
Ed25519 request signature on every request — X-Key-Id, X-Date, X-Nonce, X-Signature, plus Digest on 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:view · physical_pos:payments. Without the product the call gets 403 PRODUCT_NOT_ENABLED; without the scope 403 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.

There are two situations in which you do not know a payment's outcome: you got no response to your start request, or the payment moved to UNKNOWN. In both, money may have been taken.

🚫

NEVER start a new payment for the same sale with a new Idempotency-Key. While the outcome is uncertain the money may have been taken; a new key can charge your customer twice. Lunixi never re-charges an uncertain payment automatically.

Recovering an uncertain paymentWith no response, repeat the request with the same Idempotency-Key and body; if the payment becomes UNKNOWN, wait and do not start it again; it moves to a final status when evidence arrives, otherwise it becomes MANUAL_REVIEW and is resolved in the panel with evidence.EVIDENCENOT CONFIRMEDPANELNo responsetimeout · 5xxSame key andbody againIdempotency-KeyCurrent state200 replayed · 202or ?merchantReferenceUNKNOWNpayment.unknownWait, do notstart againdevice held ~10 minFinal statuswebhookMANUAL_REVIEWresolve with evidenceLEGENDSITUATIONYOUR MOVERESULTPANEL
Starting a new payment with a new Idempotency-Key can charge the customer twice.

If you got no response

If you got a timeout, a dropped connection or a 5xx:

  1. Repeat the request with the same Idempotency-Key and the same body. If the payment was opened you get 200 with replayed: true and its current state; otherwise it is opened now.
  2. Or find the payment by your own reference:
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments?merchantReference=ORD-2026-000123"
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"

If the payment is UNKNOWN

If no result arrives by resultDeadlineAt, the payment becomes UNKNOWN, not DECLINED, and physical_pos.payment.unknown is sent.

StageWhat happensWhat you do
UNKNOWNLunixi verifies the outcome automatically. Meanwhile (10 minutes by default) the device takes no new payment: 409 physical_pos.payment.device_busy (unknown_outcome_hold, details.retryAfterSeconds).Wait. If the outcome is confirmed, the payment moves to its final status and the matching webhook arrives.
MANUAL_REVIEWThe outcome could not be verified automatically; physical_pos.payment.manual_review is sent. The device can take payments again; the outcome keeps being queried in the background for up to 7 days.As a last resort when automatic checks cannot obtain definitive evidence, resolve the payment in the panel with evidence: bank statement, end-of-day report, device receipt and the like. A "money taken" decision needs the bank's approval code or RRN. There is no API endpoint for this.
ResolvedThe payment moves to its final status; the webhook payload carries resolvedBy: "MERCHANT".Update your order from the webhook.
  • 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).
  • If a new sale with the same reference gets 409 physical_pos.payment.previous_outcome_unknown, the previous payment (details.previousPaymentId) has not finished; do not send allowDuplicateReference: true.
  • A payment with resolvable: true can be resolved in the panel. If conflicting evidence arrives for a payment already in a final status, the status does not change and outcomeConflict becomes true; review the payment in the panel.

Listing uncertain payments

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/transactions/ambiguous?paymentStatus=MANUAL_REVIEW"
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"

All payments in UNKNOWN and MANUAL_REVIEW (roots and reversals) are returned newest first. Parameters: Transactions › Uncertain payments. Flow details: Payment Flow › Uncertain outcome.

Releasing terminal occupancy does not settle the payment

After the K-43 hold policy, the server may release the original reservation while leaving the payment in MANUAL_REVIEW. This never authorizes another charge for the same sale using a new key. Android releases only the old local reservation after durably storing a fresh, identity/challenge/original-command-bound server response; a local timeout cannot unlock it. A separate new operation must satisfy every authorization, SDK and trust gate. A transaction review does not impose a permanent device-wide ban. Repeated NFC/same-result delivery is not a new charge; identity, sandbox and storage-integrity gates still apply.

The common recovery infrastructure is implemented in source; exact vendor query/callback drivers and physical-device acceptance remain open. Fiscal documents have separate recovery limits. Document failure after bank approval never causes another charge.

Automatic missing-transaction checks and current limits

Querying a known payment differs from scanning the complete provider transaction history. The target is an initial backfill from account/terminal activation, followed by regular incremental scans, overlapping windows and recovery of gaps left by outages. Missing outcomes are matched using definitive provider evidence, without creating another payment.

The report job in source now durably plans history from the UTC creation date of the first account/merchant binding through yesterday, in bounded chunks, prioritizing the most recent 7 dates. Unfinished days are not discarded solely because they age. An old EXPIRED row stays immutable and a linked new attempt is added. The cursor tracks queued dates; report coverage separately exposes completion. A page, host or provider failure is not an empty successful report.

A newly found report candidate wakes a stopped UNKNOWN/MANUAL_REVIEW query. After the routine 7-day review window, that hint permits one fresh remote verification; it does not reset the six-command device budget. An advisory or uncertain report alone cannot approve a payment. Existing due queues no longer discard entries simply because they are 7/35 days old; this does not continually reopen every historical payment.

Repeated audits of COMPLETE days, an exact intraday activation boundary, and provider history/timezone/retention guarantees remain open work. Metropol LIVE hosts are not configured yet. This is source delivery, not production or universal provider support.