Void
- 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 cancel the whole of an approved sale before end of day. A sale whose end of day has been taken cannot be voided; you undo it with a refund.
POST /api/v1/physical-pos/payments/{paymentId}/reversals · physical_pos:payments · Idempotency-Key required
Void or refund?
settledAt set), a void is not possible. Partial and itemized refunds need the device model's support.| Situation | Use |
|---|---|
The sale is approved, end of day not taken (settledAt: null), no reversals | Void (this page) |
End of day taken (settledAt set) | Refund |
| You want to give back part of the amount | Partial Refund |
| The payment has not reached the device yet | Cancel Before Start |
Request
| Field | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | VOID. |
currency | string | Yes | The sale's currency. |
merchantReference | string | null | No | Your own reference. |
startTimeoutSeconds | integer | No | Time to start on the device, 5–30 seconds. |
Do not send amountMinor: a void always covers the whole approved amount. If you send it: 400 physical_pos.payment.amount_invalid (details.reason: full_amount_operation).
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"Outcome
A reversal opens a new child payment and returns 202 (paymentStatus: "NOT_STARTED"). You get its outcome from the child payment's webhook (data.operation, data.rootPaymentId). No separate webhook is sent for the root; read the root's current reversalStatus by retrieving it. When the void is approved, the root gets reversalStatus: "VOIDED" and no further reversal is possible on it.
Rules
- A void runs only on the sale's device and terminal. Targeting another device gets
400 physical_pos.payment.target_invalid(details.reason:original_device_required); if the device has since been linked to another terminal,409 physical_pos.payment.terminal_not_payable(terminal_changed_since_original). - The device must be ready for payments; otherwise
409 physical_pos.payment.device_offline. - A sale made directly on the device (
origin: "DEVICE_DIRECT") cannot be voided; refund it. - Cancelling a pre-authorisation closure is also a
VOID: Pre-authorisation.
Errors
| HTTP | code | When |
|---|---|---|
409 | physical_pos.payment.void_after_settlement | End of day taken; details.allowedOperation: REFUND. Refund the same payment with a new Idempotency-Key. |
409 | physical_pos.payment.not_reversible | void_after_reversal (a reversal was made before), root_not_approved (the sale is not approved or its outcome is uncertain), void_preauth_not_closed. |
409 | physical_pos.payment.reversal_in_progress | The sale has an unfinished reversal (pendingReversalId). |
400 | physical_pos.payment.amount_invalid | full_amount_operation: an amount was sent on a void. |
400 | physical_pos.payment.target_invalid | original_device_required. |
404 | physical_pos.payment.not_found | The sale does not exist. |
422 | physical_pos.payment.operation_unsupported | device_direct_refund_only, or the device model does not support voids. |
All reversal rules, device and bank selection and error reasons: Reversal Rules. All codes: Error Codes.