Physical POS
Payment Operations
Refund

Refund

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 pay the amount of an approved sale back to the customer's card. A sale whose end of day has been taken can only be undone with a refund. This page covers refunding the whole amount; for part of it see Partial Refund, for specific product lines Itemized Refund.

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

Request

FieldTypeRequiredDescription
operationstringYesREFUND.
amountMinorstringYesRefund amount in minor units, as a string. For a full refund, the whole remaining refundable amount: the root's approvedAmountMinor − reversedMinor.
currencystringYesThe sale's currency.
targetobject | nullNoTarget device, to refund on another device. If not sent, it runs on the sale's device. → Device and bank
merchantReferencestring | nullNoYour own reference.
startTimeoutSecondsintegerNoTime to start on the device, 5–30 seconds.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"REFUND","amountMinor":"4500","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: 8b4e2c71-5d3a-4f60-9a12-6c7d8e9f0a1b" \
  --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 a full refund is approved, the root gets reversalStatus: "REFUNDED" and no further reversal is possible on it.

Rules

  • The sale must be approved (APPROVED or PARTIALLY_APPROVED). On a partially approved sale, the cap is the approved amount.
  • A sale can have only one unfinished reversal at a time; a new one gets 409 physical_pos.payment.reversal_in_progress.
  • A refund can also run on another device of your organization and goes to the sale's bank; bank row selection: Device and bank.
  • Refunding the whole amount in one go does not need the device model's partial refund support.

Refunding a sale made on the device

You refund a sale made directly on the device (origin: "DEVICE_DIRECT") with this endpoint. The paymentId in the path is the sale's ID (data.paymentId of the physical_pos.payment.device_sale event).

  • Only REFUND is possible. A void gets 422 physical_pos.payment.operation_unsupported (details.reason: device_direct_refund_only).
  • The refund runs only on the device the sale was made on. Targeting another device with target gets 400 physical_pos.payment.target_invalid (details.reason: original_device_required).
  • The device must be ready for payment; otherwise 409 physical_pos.payment.device_offline. The refund is not queued. → Device readiness
  • Partial and item refunds depend on the device model's support, as for other sales (partial_amount_unsupported, itemized_unsupported). The limits, the one-pending-reversal rule and the flow of a refund with an uncertain outcome are the same as for other sales.
  • The refund goes to the sale's bank: the single bank row on the device's linked terminal that carries the sale's bank and bank terminal number (TID) is used, even if the row has since been disabled. No such row: 422 … device_sale_terminal_acquirer_not_found; more than one: 422 … device_sale_terminal_acquirer_ambiguous. If the sale's bank details are missing: 422 … original_terminal_acquirer_unknown.
  • In the refund's webhooks data.original.origin is DEVICE_DIRECT. → Webhook Events

Errors

HTTPcodeWhen
400physical_pos.payment.refund_exceeds_remainingThe amount exceeds the remaining refundable amount (details.remainingMinor, string).
400physical_pos.payment.amount_invalidAmount missing, 0 or malformed.
400physical_pos.payment.currency_mismatchThe currency differs from the sale's.
409physical_pos.payment.not_reversibleroot_not_approved, refund_after_final_reversal (the sale was voided or fully refunded).
409physical_pos.payment.reversal_in_progressThere is an unfinished reversal.
404physical_pos.payment.not_foundThe sale does not exist.
422physical_pos.payment.operation_unsupportedBank row reasons (refund_terminal_acquirer_not_on_device, refund_terminal_acquirer_ambiguous, original_terminal_acquirer_unknown …).

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