Physical POS
Payment Operations
Reversal Rules

Reversal Rules

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.

Voids, refunds, partial and itemized refunds, and pre-authorisation close and cancel all use the same endpoint. Pages per operation: Void · Refund · Partial Refund · Itemized Refund · Pre-authorisation. This page collects all of the endpoint's rules in one place.

The cURL examples compute the signature with lunixi-sign.sh: Authentication › Signing helper.

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.

Request

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

Reverses a payment or closes a pre-authorisation. The paymentId in the path is the original payment (the root); the root must be a SALE or PREAUTH_OPEN in APPROVED or PARTIALLY_APPROVED. A reversal cannot itself be reversed. The payment in the response is the new child payment: originalPaymentId and rootPaymentId point to the root.

FieldTypeRequiredDescription
operationstringYesVOID, REFUND, PREAUTH_CLOSE or PREAUTH_CANCEL.
amountMinorstringConditionalRequired on REFUND and PREAUTH_CLOSE, greater than 0. Optional on an item REFUND: the amount is derived from the items, and if you send it, it must equal the derived amount. Not sent on VOID and PREAUTH_CANCEL; the full amount applies.
currencystringYesThe root's currency.
merchantReferencestring | nullNoYour reference for the reversal; same rule as on start. The duplicate reference check does not run on reversals.
startTimeoutSecondsintegerNoAs on start, 5–30 seconds.
targetobject | nullNoREFUND only: the target device to refund on another device. If omitted, the reversal runs on the root's device. A sale made directly on the device is not refunded on another device. → Device and bank
itemsarrayNoREFUND only: item refund lines { lineNo, quantityMilli, amountMinor? }, at most 500. For an amount refund omit the field; an empty array is rejected. → Item refunds

A supplied amountMinor must be a canonical positive minor-unit string; explicit null is rejected. Omit it for VOID and PREAUTH_CANCEL. For an itemized REFUND, omission derives the total from the items; amount-based REFUND and PREAUTH_CLOSE still require the amount.

Which reversal when

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.
OperationRootAmountWhen
VOIDSALEThe full approved amountWhile the root has no reversal (reversalStatus: "NONE") and before end-of-day. Not available on a sale made directly on the device.
VOIDPREAUTH_OPENThe full closed amountAfter the pre-authorisation was closed (PREAUTH_CLOSED): voids the close.
REFUNDSALEAt most: approved − refunded − closedNONE or PARTIALLY_REFUNDED; several partial refunds are allowed.
REFUNDPREAUTH_OPENAt most: closed − refundedPREAUTH_CLOSED or PARTIALLY_REFUNDED.
PREAUTH_CLOSEPREAUTH_OPENThe approved amount plus the margin the device model allowsOn an open pre-authorisation (NONE).
PREAUTH_CANCELPREAUTH_OPENThe full open amountOn an open pre-authorisation (NONE).
  • Device model support: a partial refund (less than the full approved amount, or a new refund on a sale that already has a refund, i.e. several refunds), a partial pre-authorisation close (less than the open amount) and item refunds require the device model to support them. If it does not, the request gets 422 physical_pos.payment.operation_unsupported with details.reason partial_amount_unsupported or itemized_unsupported. Void, pre-authorisation cancel and a single refund of the full amount are not subject to this.
  • One pending reversal: while the root has a reversal that has not completed, a new one gets 409 physical_pos.payment.reversal_in_progress. The pending reversal is in the root's pendingReversalId.
  • The amount of a pending reversal is held on the root (reversalReservedMinor). When the child becomes APPROVED the amount is final; when it becomes DECLINED, CANCELLED, EXPIRED or FAILED the held amount is released. While the child is UNKNOWN or MANUAL_REVIEW the held amount is kept; this prevents the same amount from being refunded twice.
  • On a partially approved (PARTIALLY_APPROVED) payment, the limits are based on the approved amount.
  • End of day: a void of a settled payment gets 409 physical_pos.payment.void_after_settlement (details.allowedOperation: REFUND); return the amount with a REFUND on the same payment. The rule does not depend on the device model. → End of day and voids

Device and bank

  • Void and pre-authorisation operations run only on the root's device and terminal. Targeting another device gets 400 physical_pos.payment.target_invalid (details.reason: original_device_required). If the root's device has since been linked to another terminal: 409 physical_pos.payment.terminal_not_payable (details.reason: terminal_changed_since_original).
  • A refund can also run on another device of your organization and goes to the sale's bank:
    • On the same terminal the refund uses the sale's bank row, even if the row has since been disabled.
    • On another terminal, the single bank row of that terminal with the same bank and the same merchant number as the sale, active, mapped and listing the currency, is used. No such row: 422 … refund_terminal_acquirer_not_on_device; more than one: 422 … refund_terminal_acquirer_ambiguous.
    • If no bank row was chosen on the sale (terminalAcquirerId: null), the refund cannot run on another terminal: 422 … original_terminal_acquirer_unknown. It can run on the same terminal.
  • A sale made directly on the device is refunded only on that sale's device. → Refunding a sale made on the device
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"

Body of a partial amount refund (if the device model supports partial refunds): {"operation":"REFUND","amountMinor":"1500","currency":"TRY"}. Item refunds: Items › Item refunds.

A new reversal returns 202, a repeat 200; data: { "payment": { … }, "replayed": false }. The child payment starts with operation: "VOID", paymentStatus: "NOT_STARTED".

Errors (in addition to those of starting a payment):

HTTPcodeWhen
404physical_pos.payment.not_foundRoot payment not found.
400physical_pos.payment.amount_invaliddetails.reason: not_positive (0 or negative), full_amount_operation (an amount on VOID / PREAUTH_CANCEL), preauth_close_exceeds_tolerance, item_amount_mismatch (differs from the amount derived from the items; details.expectedMinor).
400physical_pos.payment.refund_exceeds_remainingThe refund exceeds the remaining refundable amount (details.remainingMinor, a string).
400physical_pos.payment.currency_mismatchCurrency differs from the root's.
400physical_pos.payment.refund_items_invalidA refund item is invalid. → Item refunds
409physical_pos.payment.not_reversibleThis reversal is not allowed on this root (see below).
409physical_pos.payment.void_after_settlementVoid of a settled payment; details.allowedOperation: REFUND. Refund it instead.
409physical_pos.payment.reversal_in_progressThe root has a reversal that has not completed.
409physical_pos.payment.terminal_not_payableterminal_changed_since_original or the terminal is not ready.
422physical_pos.payment.operation_unsupportedoperation_not_reversal, item refund or bank row reasons (see below).

details.reason of physical_pos.payment.not_reversible:

details.reasonMeaning
root_operationThe root is not a SALE or PREAUTH_OPEN.
root_not_approvedThe root is not approved (including uncertain outcomes).
void_after_reversalThe root already has a reversal; void is not possible.
void_preauth_not_closedA pre-authorisation cannot be voided before it is closed.
refund_after_final_reversalThe root was voided, fully refunded or its pre-authorisation cancelled.
refund_preauth_not_closedAn unclosed pre-authorisation cannot be refunded; cancel it.
preauth_operation_on_saleA pre-authorisation operation cannot be applied to a sale.
preauth_not_openThe pre-authorisation is not open.

Additional details.reason values of physical_pos.payment.operation_unsupported on reversals:

details.reasonMeaning
operation_not_reversaloperation cannot be used on this endpoint.
item_refund_root_without_itemsItem refund on a sale without items.
item_refund_root_not_saleItem refunds are only for sales.
item_refund_partially_approvedNo item refund on a partially approved sale; refund an amount instead.
partial_amount_unsupportedThe device model does not support a partial amount refund or a partial pre-authorisation close. Use the full amount.
itemized_unsupportedThe device model does not support item refunds. Refund an amount instead.
original_reference_invalidThe original transaction's bank reference cannot be passed to the device (details.field).
original_terminal_closedThe sale's terminal is closed.
original_terminal_acquirer_unknownThe sale's bank row is not known.
original_terminal_acquirer_missing · original_terminal_acquirer_unmappedThe sale's bank row no longer exists or its mapping is broken.
refund_terminal_acquirer_not_on_device · refund_terminal_acquirer_ambiguousThe target device's terminal has no eligible bank row, or more than one.
device_direct_refund_onlyA sale made directly on the device can only be refunded.
device_sale_terminal_acquirer_not_found · device_sale_terminal_acquirer_ambiguousThe device's terminal has no bank row matching the sale's bank and TID, or more than one.

If the device cannot find the original transaction, the child payment becomes FAILED (statusReason: DEVICE_REJECTED_ORIGINAL_NOT_FOUND) and the amount held on the root is released.