Cancel Before Start
- 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 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 state | Result |
|---|---|
NOT_STARTED and the command not sent to the device | The 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_PROGRESS | If 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_REVIEW | 409 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.