Pre-authorisation
- 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. 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.
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.
| Step | Endpoint | operation |
|---|---|---|
| Open a pre-authorisation | POST /api/v1/physical-pos/payments | PREAUTH_OPEN |
| Close (capture) | POST /api/v1/physical-pos/payments/{paymentId}/reversals | PREAUTH_CLOSE |
| Cancel (release the hold) | POST /api/v1/physical-pos/payments/{paymentId}/reversals | PREAUTH_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"); otherwise409 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 incapturedMinor.
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
VOIDreverses the whole captured amount. → Void - Refund: a
REFUNDreturns at mostcapturedMinor − reversedMinorof 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.