Physical POS
Payment Operations
Pre-authorisation

Pre-authorisation

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: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.

You hold an amount on the card and finalise it later (hotels, car rental and the like). The flow has three steps: open, close (capture) or cancel.

StepEndpointoperation
Open a pre-authorisationPOST /api/v1/physical-pos/paymentsPREAUTH_OPEN
Close (capture)POST /api/v1/physical-pos/payments/{paymentId}/reversalsPREAUTH_CLOSE
Cancel (release the hold)POST /api/v1/physical-pos/payments/{paymentId}/reversalsPREAUTH_CANCEL

All three steps need the physical_pos:payments scope and an Idempotency-Key.

Open

The request is the same as a sale with operation: "PREAUTH_OPEN". Do not send instalments (installmentCount) or items (items).

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
BODY='{"operation":"PREAUTH_OPEN","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"50000","currency":"TRY","merchantReference":"RES-2026-000045"}'
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: 5c1e7a90-2f4b-4d38-b6a1-9e0f1a2b3c4d" \
  --data-raw "$BODY"

Close

You capture the held amount. amountMinor is required.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"PREAUTH_CLOSE","amountMinor":"42000","currency":"TRY"}'
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: 7e3b5c10-8a2d-4f61-9b47-2c3d4e5f6a7b" \
  --data-raw "$BODY"
  • The pre-authorisation must be open (reversalStatus: "NONE"); otherwise 409 physical_pos.payment.not_reversible (preauth_not_open).
  • The amount is at most the approved amount plus the margin the device model allows; above it 400 physical_pos.payment.amount_invalid (preauth_close_exceeds_tolerance).
  • Closing for less than the open amount needs the device model's partial close support; otherwise 422 … partial_amount_unsupported.
  • When the close is approved, the root gets reversalStatus: "PREAUTH_CLOSED" and the captured amount is in capturedMinor.

Cancel

You release the hold; no amount is sent ({"operation":"PREAUTH_CANCEL","currency":"TRY"}). The pre-authorisation must be open. When approved, reversalStatus becomes "PREAUTH_CANCELLED".

After closing

  • Cancel the closure: a VOID reverses the whole captured amount. → Void
  • Refund: a REFUND returns at most capturedMinor − reversedMinor of the captured amount. → Refund
  • An unclosed pre-authorisation cannot be refunded or voided: 409 … refund_preauth_not_closed / void_preauth_not_closed; cancel it.
  • An expired pre-authorisation gets reversalStatus: "PREAUTH_EXPIRED" and takes no further reversals.

Rules

  • Close, cancel and cancelling the closure run only on the pre-authorisation's device and terminal (original_device_required, terminal_changed_since_original).
  • Pre-authorisation operations cannot be applied to a sale: 409 physical_pos.payment.not_reversible (preauth_operation_on_sale).

A reversal opens a new child payment and returns 202 (paymentStatus: "NOT_STARTED"). You get its outcome from the child payment's webhook (data.operation, data.rootPaymentId). No separate webhook is sent for the root; read the root's current reversalStatus by retrieving it.

All reversal rules, device and bank selection and error reasons: Reversal Rules. All codes: Error Codes.