Refund
- 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 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
| Field | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | REFUND. |
amountMinor | string | Yes | Refund amount in minor units, as a string. For a full refund, the whole remaining refundable amount: the root's approvedAmountMinor − reversedMinor. |
currency | string | Yes | The sale's currency. |
target | object | null | No | Target device, to refund on another device. If not sent, it runs on the sale's device. → Device and bank |
merchantReference | string | null | No | Your own reference. |
startTimeoutSeconds | integer | No | Time 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 (
APPROVEDorPARTIALLY_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
REFUNDis possible. A void gets422 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
targetgets400 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.originisDEVICE_DIRECT. → Webhook Events
Errors
| HTTP | code | When |
|---|---|---|
400 | physical_pos.payment.refund_exceeds_remaining | The amount exceeds the remaining refundable amount (details.remainingMinor, string). |
400 | physical_pos.payment.amount_invalid | Amount missing, 0 or malformed. |
400 | physical_pos.payment.currency_mismatch | The currency differs from the sale's. |
409 | physical_pos.payment.not_reversible | root_not_approved, refund_after_final_reversal (the sale was voided or fully refunded). |
409 | physical_pos.payment.reversal_in_progress | There is an unfinished reversal. |
404 | physical_pos.payment.not_found | The sale does not exist. |
422 | physical_pos.payment.operation_unsupported | Bank 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.