Physical POS
Payment Operations
Void

Void

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 cancel the whole of an approved sale before end of day. A sale whose end of day has been taken cannot be voided; you undo it with a refund.

POST /api/v1/physical-pos/payments/{paymentId}/reversals · physical_pos:payments · Idempotency-Key required

Void or refund?

Void or refund?If an approved sale is undone in full before end of day, void it; otherwise refund the whole amount, or make an itemized refund by product lines or a partial refund by amount; a payment that has not reached the device is cancelled before start.YESYESYESNONONOUndo an approved saleBefore end of dayand in full?In full?By productlines?Voidoperation: VOIDRefundREFUND · full amountItemized refundREFUND + itemsPartial refundREFUND + amountMinorNot on device yetCancel before startLEGENDQUESTIONVOIDREFUNDNOT STARTED
Once end of day is taken (settledAt set), a void is not possible. Partial and itemized refunds need the device model's support.
SituationUse
The sale is approved, end of day not taken (settledAt: null), no reversalsVoid (this page)
End of day taken (settledAt set)Refund
You want to give back part of the amountPartial Refund
The payment has not reached the device yetCancel Before Start

Request

FieldTypeRequiredDescription
operationstringYesVOID.
currencystringYesThe sale's currency.
merchantReferencestring | nullNoYour own reference.
startTimeoutSecondsintegerNoTime to start on the device, 5–30 seconds.

Do not send amountMinor: a void always covers the whole approved amount. If you send it: 400 physical_pos.payment.amount_invalid (details.reason: full_amount_operation).

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"VOID","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: 3d2a9f10-6b1e-4c7a-8e55-0f1d2c3b4a59" \
  --data-raw "$BODY"

Outcome

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. When the void is approved, the root gets reversalStatus: "VOIDED" and no further reversal is possible on it.

Rules

  • A void runs only on the sale's device and terminal. Targeting another device gets 400 physical_pos.payment.target_invalid (details.reason: original_device_required); if the device has since been linked to another terminal, 409 physical_pos.payment.terminal_not_payable (terminal_changed_since_original).
  • The device must be ready for payments; otherwise 409 physical_pos.payment.device_offline.
  • A sale made directly on the device (origin: "DEVICE_DIRECT") cannot be voided; refund it.
  • Cancelling a pre-authorisation closure is also a VOID: Pre-authorisation.

Errors

HTTPcodeWhen
409physical_pos.payment.void_after_settlementEnd of day taken; details.allowedOperation: REFUND. Refund the same payment with a new Idempotency-Key.
409physical_pos.payment.not_reversiblevoid_after_reversal (a reversal was made before), root_not_approved (the sale is not approved or its outcome is uncertain), void_preauth_not_closed.
409physical_pos.payment.reversal_in_progressThe sale has an unfinished reversal (pendingReversalId).
400physical_pos.payment.amount_invalidfull_amount_operation: an amount was sent on a void.
400physical_pos.payment.target_invalidoriginal_device_required.
404physical_pos.payment.not_foundThe sale does not exist.
422physical_pos.payment.operation_unsupporteddevice_direct_refund_only, or the device model does not support voids.

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