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, 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 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 gets400 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 isAPPROVED; it is released onDECLINED,CANCELLED,EXPIREDorFAILED; it stays reserved while the outcome is uncertain. This prevents refunding the same amount twice.
What you see on the root
| Situation | reversalStatus | reversedMinor |
|---|---|---|
| First partial refund approved | PARTIALLY_REFUNDED | Total of approved refunds |
| Further refunds covered the whole amount | REFUNDED | The whole approved amount |
All reversal rules, device and bank selection and error reasons: Reversal Rules. All codes: Error Codes.