Physical POS
Payment Operations
Unmatched Refund

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, 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 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_refund or daily, details.limitMinor as 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.