Physical POS
Payment Operations
Partial Refund

Partial 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 refund part of the sale amount; you can make further refunds for the remaining amount later.

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

The request is the same as a refund; amountMinor is less than the remaining refundable amount:

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"REFUND","amountMinor":"1500","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: a6f0c3d2-1b8e-4e57-8c90-3d4e5f6a7b8c" \
  --data-raw "$BODY"

Rules

  • The device model must support partial refunds. Refunding less than the whole amount, and a new refund on a sale that has already been refunded, count as partial. If not supported: 422 physical_pos.payment.operation_unsupported (details.reason: partial_amount_unsupported); refund the whole amount in one go.
  • You can make several partial refunds, but only one unfinished refund at a time (409 physical_pos.payment.reversal_in_progress). Wait for the previous one's outcome.
  • Remaining refundable amount: the root's approvedAmountMinor − reversedMinor. A request above it gets 400 physical_pos.payment.refund_exceeds_remaining (details.remainingMinor).
  • The amount of an unfinished refund is reserved on the root (reversalReservedMinor). It becomes final when the refund is APPROVED; it is released on DECLINED, CANCELLED, EXPIRED or FAILED; it stays reserved while the outcome is uncertain. This prevents refunding the same amount twice.

What you see on the root

SituationreversalStatusreversedMinor
First partial refund approvedPARTIALLY_REFUNDEDTotal of approved refunds
Further refunds covered the whole amountREFUNDEDThe whole approved amount

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