Physical POS
Payment Operations
Itemized Refund

Itemized 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.

On a sale started with product lines, you send the lines and quantities you want to refund; the refund amount and taxes are calculated on the server.

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

Request

You refund specific lines of a sale with items, by quantity. Send the request to the reversal endpoint with operation: "REFUND" and items:

FieldTypeRequiredDescription
lineNointegerYesThe line number on the sale.
quantityMilliintegerYesQuantity to refund × 1000.
amountMinorstringNoConfirmation of the line's refund amount. Omit to use the amount the server computes; an explicit value must equal it. Explicit null is rejected.

lineNo must be 1–500, quantityMilli a JSON integer of 1 or more, and an explicitly supplied amountMinor a canonical positive minor-unit string; otherwise 400 physical_pos.payment.refund_items_invalid (details.field: a dotted path such as items.0.quantityMilli; details.reason: line_no_invalid, quantity_invalid or amount_invalid; invalid if items is not an array or a line is not an object). An undefined field in a line gets 400 VALIDATION_ERROR.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"REFUND","currency":"TRY","items":[{"lineNo":1,"quantityMilli":1000}]}'
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: 1c9d3e52-7a40-4b8e-9d61-2e5f7a9c0b13" \
  --data-raw "$BODY"

In the example one tea of the two-tea line is refunded; the child payment gets amountMinor: "1500" (computed by the server).

Amount calculation:

  • The refund amount is computed from the items. The payment's amountMinor field is optional; if you send it, it must equal the computed total, otherwise 400 physical_pos.payment.amount_invalid (details.reason: item_amount_mismatch, details.expectedMinor).
  • For a partial quantity the line amount is quantityMilli × unitPriceMinor / 1000 rounded half up, leaving at least one minor unit for the remaining quantity. If the result drops to 0, quantity_too_small comes back: refund the whole remaining quantity.
  • When the last units of a line are refunded, the whole remaining amount is refunded; the line's refunds add up exactly to the line total.
  • Taxes are computed proportionally from the line's stored breakdown; on the last unit the remainder of each tax type is returned.

Eligibility:

  • Item refunds require the device model to support them; otherwise 422 physical_pos.payment.operation_unsupported (details.reason: itemized_unsupported). Refunding part of a sale, or a second refund on the same sale, counts as a partial refund and also requires the device model to support partial refunds (partial_amount_unsupported).
  • The root must be a SALE (otherwise 422 … item_refund_root_not_sale), must have items (otherwise item_refund_root_without_items) and must be fully approved (APPROVED). No item refund on a partially approved sale (item_refund_partially_approved); refund an amount instead.
  • Item refunds and amount refunds can be combined on the same sale. An amount refund does not reduce the refundable quantity of the lines, but the sale's total refundable amount is checked on every refund. For example, if 4000 kuruş were refunded by amount on a 4500-kuruş sale, refunding the whole tea line gets 400 physical_pos.payment.refund_exceeds_remaining.

Refund lines: refundItems

When the child payment of an item refund is read, the refundItems array comes back:

FieldTypeDescription
lineNointegerThe line number on the sale.
name, unitCode, unitPriceMinor, taxGroupCodeThe sale line's values.
quantityMilliintegerRefunded quantity × 1000.
amountMinorstringThe line's refund amount.
netMinorstringThe part of the refund amount excluding taxes.
taxesarray{ taxType, baseMinor, amountMinor }: the refunded tax breakdown.

Item refund status: refundStatus

  • NONE, PARTIAL and FULL reflect only approved item refunds: PARTIAL, the refunded quantity is greater than 0 and less than the sold quantity; FULL, the whole line was refunded.
  • Void and amount refunds do not change the item status. On a sale that was voided or fully refunded by amount, refundStatus can stay NONE.
  • The real state of the money is on the root: see the reversedMinor and reversalStatus fields.
  • An item refund that has not completed shows in reservedQuantityMilli and reservedMinor.
  • If the bank approves an amount different from the requested one on an item refund, the lines are counted as refunded as they were held; the root's reversedMinor shows the amount the bank approved and the child payment gets outcomeConflict: true.

Errors

400 physical_pos.payment.refund_items_invalid (refund items). details.field gives the path of the field in the request (such as items[0].quantityMilli; items for the whole list; a dotted path such as items.0.quantityMilli for the type and limit check made when the request is received).

details.reasonMeaning
invaliditems is not an array, or one of the lines is not an object.
emptyitems is an empty array.
too_manyMore than 500 lines.
line_no_invalidThe line number is invalid.
line_duplicateThe same line was sent twice.
line_not_foundThe sale has no line with this number.
quantity_invalidThe quantity is 0 or invalid.
quantity_exceeds_remainingThe quantity exceeds the line's remaining refundable quantity; details.remainingQuantityMilli.
quantity_too_smallThe quantity's amount drops to 0; refund the whole remaining quantity (details.remainingQuantityMilli).
amount_invalidThe line's amountMinor is invalid.
amount_mismatchThe line's amountMinor differs from the computed amount; details.expectedMinor.

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