Reversal Rules
- 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.
Voids, refunds, partial and itemized refunds, and pre-authorisation close and cancel all use the same endpoint. Pages per operation: Void · Refund · Partial Refund · Itemized Refund · Pre-authorisation. This page collects all of the endpoint's rules in one place.
The cURL examples compute the signature with lunixi-sign.sh: Authentication › Signing helper.
Starting a payment or a reversal runs when a payment capability definition exists for the target device's model. On a device without a capability definition the request gets 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) once the device is found and its terminal link and communication channel are checked; no payment record is created.
Request
POST /api/v1/physical-pos/payments/{paymentId}/reversals · Idempotency-Key required
Reverses a payment or closes a pre-authorisation. The paymentId in the path is the original payment (the root); the root must be a SALE or PREAUTH_OPEN in APPROVED or PARTIALLY_APPROVED. A reversal cannot itself be reversed. The payment in the response is the new child payment: originalPaymentId and rootPaymentId point to the root.
| Field | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | VOID, REFUND, PREAUTH_CLOSE or PREAUTH_CANCEL. |
amountMinor | string | Conditional | Required on REFUND and PREAUTH_CLOSE, greater than 0. Optional on an item REFUND: the amount is derived from the items, and if you send it, it must equal the derived amount. Not sent on VOID and PREAUTH_CANCEL; the full amount applies. |
currency | string | Yes | The root's currency. |
merchantReference | string | null | No | Your reference for the reversal; same rule as on start. The duplicate reference check does not run on reversals. |
startTimeoutSeconds | integer | No | As on start, 5–30 seconds. |
target | object | null | No | REFUND only: the target device to refund on another device. If omitted, the reversal runs on the root's device. A sale made directly on the device is not refunded on another device. → Device and bank |
items | array | No | REFUND only: item refund lines { lineNo, quantityMilli, amountMinor? }, at most 500. For an amount refund omit the field; an empty array is rejected. → Item refunds |
A supplied amountMinor must be a canonical positive minor-unit string; explicit null is rejected. Omit it for VOID and PREAUTH_CANCEL. For an itemized REFUND, omission derives the total from the items; amount-based REFUND and PREAUTH_CLOSE still require the amount.
Which reversal when
settledAt set), a void is not possible. Partial and itemized refunds need the device model's support.| Operation | Root | Amount | When |
|---|---|---|---|
VOID | SALE | The full approved amount | While the root has no reversal (reversalStatus: "NONE") and before end-of-day. Not available on a sale made directly on the device. |
VOID | PREAUTH_OPEN | The full closed amount | After the pre-authorisation was closed (PREAUTH_CLOSED): voids the close. |
REFUND | SALE | At most: approved − refunded − closed | NONE or PARTIALLY_REFUNDED; several partial refunds are allowed. |
REFUND | PREAUTH_OPEN | At most: closed − refunded | PREAUTH_CLOSED or PARTIALLY_REFUNDED. |
PREAUTH_CLOSE | PREAUTH_OPEN | The approved amount plus the margin the device model allows | On an open pre-authorisation (NONE). |
PREAUTH_CANCEL | PREAUTH_OPEN | The full open amount | On an open pre-authorisation (NONE). |
- Device model support: a partial refund (less than the full approved amount, or a new refund on a sale that already has a refund, i.e. several refunds), a partial pre-authorisation close (less than the open amount) and item refunds require the device model to support them. If it does not, the request gets
422 physical_pos.payment.operation_unsupportedwithdetails.reasonpartial_amount_unsupportedoritemized_unsupported. Void, pre-authorisation cancel and a single refund of the full amount are not subject to this. - One pending reversal: while the root has a reversal that has not completed, a new one gets
409 physical_pos.payment.reversal_in_progress. The pending reversal is in the root'spendingReversalId. - The amount of a pending reversal is held on the root (
reversalReservedMinor). When the child becomesAPPROVEDthe amount is final; when it becomesDECLINED,CANCELLED,EXPIREDorFAILEDthe held amount is released. While the child isUNKNOWNorMANUAL_REVIEWthe held amount is kept; this prevents the same amount from being refunded twice. - On a partially approved (
PARTIALLY_APPROVED) payment, the limits are based on the approved amount. - End of day: a void of a settled payment gets
409 physical_pos.payment.void_after_settlement(details.allowedOperation:REFUND); return the amount with aREFUNDon the same payment. The rule does not depend on the device model. → End of day and voids
Device and bank
- Void and pre-authorisation operations run only on the root's device and terminal. Targeting another device gets
400 physical_pos.payment.target_invalid(details.reason:original_device_required). If the root's device has since been linked to another terminal:409 physical_pos.payment.terminal_not_payable(details.reason:terminal_changed_since_original). - A refund can also run on another device of your organization and goes to the sale's bank:
- On the same terminal the refund uses the sale's bank row, even if the row has since been disabled.
- On another terminal, the single bank row of that terminal with the same bank and the same merchant number as the sale, active, mapped and listing the currency, is used. No such row:
422 … refund_terminal_acquirer_not_on_device; more than one:422 … refund_terminal_acquirer_ambiguous. - If no bank row was chosen on the sale (
terminalAcquirerId: null), the refund cannot run on another terminal:422 … original_terminal_acquirer_unknown. It can run on the same terminal.
- A sale made directly on the device is refunded only on that sale's device. → Refunding a sale made on the device
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"VOID","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: 3d2a9f10-6b1e-4c7a-8e55-0f1d2c3b4a59" \
--data-raw "$BODY"Body of a partial amount refund (if the device model supports partial refunds): {"operation":"REFUND","amountMinor":"1500","currency":"TRY"}. Item refunds: Items › Item refunds.
A new reversal returns 202, a repeat 200; data: { "payment": { … }, "replayed": false }. The child payment starts with operation: "VOID", paymentStatus: "NOT_STARTED".
Errors (in addition to those of starting a payment):
| HTTP | code | When |
|---|---|---|
404 | physical_pos.payment.not_found | Root payment not found. |
400 | physical_pos.payment.amount_invalid | details.reason: not_positive (0 or negative), full_amount_operation (an amount on VOID / PREAUTH_CANCEL), preauth_close_exceeds_tolerance, item_amount_mismatch (differs from the amount derived from the items; details.expectedMinor). |
400 | physical_pos.payment.refund_exceeds_remaining | The refund exceeds the remaining refundable amount (details.remainingMinor, a string). |
400 | physical_pos.payment.currency_mismatch | Currency differs from the root's. |
400 | physical_pos.payment.refund_items_invalid | A refund item is invalid. → Item refunds |
409 | physical_pos.payment.not_reversible | This reversal is not allowed on this root (see below). |
409 | physical_pos.payment.void_after_settlement | Void of a settled payment; details.allowedOperation: REFUND. Refund it instead. |
409 | physical_pos.payment.reversal_in_progress | The root has a reversal that has not completed. |
409 | physical_pos.payment.terminal_not_payable | terminal_changed_since_original or the terminal is not ready. |
422 | physical_pos.payment.operation_unsupported | operation_not_reversal, item refund or bank row reasons (see below). |
details.reason of physical_pos.payment.not_reversible:
details.reason | Meaning |
|---|---|
root_operation | The root is not a SALE or PREAUTH_OPEN. |
root_not_approved | The root is not approved (including uncertain outcomes). |
void_after_reversal | The root already has a reversal; void is not possible. |
void_preauth_not_closed | A pre-authorisation cannot be voided before it is closed. |
refund_after_final_reversal | The root was voided, fully refunded or its pre-authorisation cancelled. |
refund_preauth_not_closed | An unclosed pre-authorisation cannot be refunded; cancel it. |
preauth_operation_on_sale | A pre-authorisation operation cannot be applied to a sale. |
preauth_not_open | The pre-authorisation is not open. |
Additional details.reason values of physical_pos.payment.operation_unsupported on reversals:
details.reason | Meaning |
|---|---|
operation_not_reversal | operation cannot be used on this endpoint. |
item_refund_root_without_items | Item refund on a sale without items. |
item_refund_root_not_sale | Item refunds are only for sales. |
item_refund_partially_approved | No item refund on a partially approved sale; refund an amount instead. |
partial_amount_unsupported | The device model does not support a partial amount refund or a partial pre-authorisation close. Use the full amount. |
itemized_unsupported | The device model does not support item refunds. Refund an amount instead. |
original_reference_invalid | The original transaction's bank reference cannot be passed to the device (details.field). |
original_terminal_closed | The sale's terminal is closed. |
original_terminal_acquirer_unknown | The sale's bank row is not known. |
original_terminal_acquirer_missing · original_terminal_acquirer_unmapped | The sale's bank row no longer exists or its mapping is broken. |
refund_terminal_acquirer_not_on_device · refund_terminal_acquirer_ambiguous | The target device's terminal has no eligible bank row, or more than one. |
device_direct_refund_only | A sale made directly on the device can only be refunded. |
device_sale_terminal_acquirer_not_found · device_sale_terminal_acquirer_ambiguous | The device's terminal has no bank row matching the sale's bank and TID, or more than one. |
If the device cannot find the original transaction, the child payment becomes FAILED (statusReason: DEVICE_REJECTED_ORIGINAL_NOT_FOUND) and the amount held on the root is released.