Physical POS
Payment Operations
Cancel Before Start

Cancel Before Start

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 stop a payment whose request has not reached the device yet; no money is taken from the customer's card. An approved sale is undone not with this endpoint but with Void or Refund.

Cancel

POST /api/v1/physical-pos/payments/{paymentId}/cancel · Idempotency-Key optional · body {}

Cancels a payment whose command has not yet reached the device. To reverse an approved payment use a reversal. The body is an empty object ({}); any other field gets 400 VALIDATION_ERROR.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/cancel"
BODY='{}'
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" \
  --data-raw "$BODY"
Payment stateResult
NOT_STARTED and the command not sent to the deviceThe payment is cancelled: paymentStatus: "EXPIRED", statusReason: "MERCHANT_CANCELLED_BEFORE_DISPATCH", replayed: false. A physical_pos.payment.expired webhook is sent.
In a final status (including APPROVED)The payment does not change; its current state comes back with replayed: true.
Command sent to the device, or IN_PROGRESSIf the device or its vendor supports releasing a transaction that has not started, the release is requested and the payment's current state is returned with replayed: false; the payment's status does not change in this response. The payment closes when its outcome arrives (CANCELLED if released). Otherwise 409 physical_pos.payment.not_cancellable (details.reason: command_dispatched).
UNKNOWN or MANUAL_REVIEW409 physical_pos.payment.not_cancellable (details.reason: outcome_unknown). Money may have been taken.
⚠️

When the cancel response is 200, read paymentStatus. Unless it is EXPIRED with MERCHANT_CANCELLED_BEFORE_DISPATCH, the cancellation did not happen: the payment is either already in a final status or still running on the device. Follow the outcome through webhooks or by retrieving the payment.

Response (200): { "payment": { … }, "replayed": false }. Repeating a cancellation is safe. Other errors: 404 physical_pos.payment.not_found, 403 physical_pos.environment.test_key_read_only, 400 physical_pos.idempotency.key_invalid (a key was sent but is malformed), 409 physical_pos.idempotency_mismatch (the key was used on another payment or operation), 503 physical_pos.service.busy.