Unmatched 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 start a refund that is not linked to a sale from the same endpoint as a sale with operation: "REFUND_UNMATCHED". The customer presents the card on the device; the refund goes to the card.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
BODY='{"operation":"REFUND_UNMATCHED","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"2500","currency":"TRY","merchantReference":"RET-2026-000012"}'
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: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
--data-raw "$BODY"Rules
An unmatched refund (REFUND_UNMATCHED) is a refund not linked to a sale: money is refunded to the customer's card for a sale that has no record in Lunixi. It is made with the start endpoint.
- It is off by default in your account settings; while off, the request gets
422 physical_pos.payment.operation_unsupported(details.reason:disabled_by_setting). The setting is managed in the panel. - If the setting is on as "panel only", a request with an API key gets
403 physical_pos.auth.api_key_not_allowed. - The currency must be the one in the setting; otherwise
400 physical_pos.payment.currency_unsupported(details.reason:unmatched_refund_currency). - A per-refund and a daily limit apply: when exceeded,
422 physical_pos.payment.unmatched_refund_limit_exceeded(details.reason:per_refundordaily,details.limitMinoras a string). - Every unmatched refund triggers an e-mail and a panel notification to the account owner.
You get the outcome by webhook: physical_pos.payment.approved, …partially_approved, …declined, …cancelled, …expired, …failed, …unknown or …manual_review. If you do not want to wait for a webhook, retrieve the payment.