Itemized 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.
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:
| Field | Type | Required | Description |
|---|---|---|---|
lineNo | integer | Yes | The line number on the sale. |
quantityMilli | integer | Yes | Quantity to refund × 1000. |
amountMinor | string | No | Confirmation 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
amountMinorfield is optional; if you send it, it must equal the computed total, otherwise400 physical_pos.payment.amount_invalid(details.reason:item_amount_mismatch,details.expectedMinor). - For a partial quantity the line amount is
quantityMilli × unitPriceMinor / 1000rounded half up, leaving at least one minor unit for the remaining quantity. If the result drops to 0,quantity_too_smallcomes 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(otherwise422 … item_refund_root_not_sale), must have items (otherwiseitem_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:
| Field | Type | Description |
|---|---|---|
lineNo | integer | The line number on the sale. |
name, unitCode, unitPriceMinor, taxGroupCode | The sale line's values. | |
quantityMilli | integer | Refunded quantity × 1000. |
amountMinor | string | The line's refund amount. |
netMinor | string | The part of the refund amount excluding taxes. |
taxes | array | { taxType, baseMinor, amountMinor }: the refunded tax breakdown. |
Item refund status: refundStatus
NONE,PARTIALandFULLreflect 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,
refundStatuscan stayNONE. - The real state of the money is on the root: see the
reversedMinorandreversalStatusfields. - An item refund that has not completed shows in
reservedQuantityMilliandreservedMinor. - 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
reversedMinorshows the amount the bank approved and the child payment getsoutcomeConflict: 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.reason | Meaning |
|---|---|
invalid | items is not an array, or one of the lines is not an object. |
empty | items is an empty array. |
too_many | More than 500 lines. |
line_no_invalid | The line number is invalid. |
line_duplicate | The same line was sent twice. |
line_not_found | The sale has no line with this number. |
quantity_invalid | The quantity is 0 or invalid. |
quantity_exceeds_remaining | The quantity exceeds the line's remaining refundable quantity; details.remainingQuantityMilli. |
quantity_too_small | The quantity's amount drops to 0; refund the whole remaining quantity (details.remainingQuantityMilli). |
amount_invalid | The line's amountMinor is invalid. |
amount_mismatch | The line's amountMinor differs from the computed amount; details.expectedMinor. |
All reversal rules, device and bank selection and error reasons: Reversal Rules.