Physical POS
API Reference
Start End of Day

Start End of Day

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:view · 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 can start end of day on a device from your own server. Lunixi sends a signed end-of-day command to the device; the device takes end of day with the banks and reports the result. Every start opens an end-of-day run (run) record. Scheduled end of day under an end-of-day policy uses the same run record.

MethodPathScope
POST/api/v1/physical-pos/devices/{deviceId}/settlementphysical_pos:payments
GET/api/v1/physical-pos/settlement-runsphysical_pos:view or physical_pos:payments
GET/api/v1/physical-pos/settlement-runs/{runId}physical_pos:view or physical_pos:payments
  • You get the end-of-day result (bank rows and the difference from Lunixi's records) from the End-of-Day Records endpoint and the physical_pos.settlement.completed webhook. The run record only tracks the start of end of day and the state of its command.
  • A test key reads runs; starting gets 403 physical_pos.environment.test_key_read_only. → Environments
  • You can also take end of day by hand on the device; no run record is opened then, and the result still reaches End-of-Day Records and the webhook (source: "DEVICE").

The cURL examples compute the signature with lunixi-sign.sh: Authentication › Signing helper.

Start end of day

POST /api/v1/physical-pos/devices/{deviceId}/settlement · physical_pos:payments

The body is empty; the Idempotency-Key header is required. → Conventions › Idempotency-Key

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/settlement"
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" \
  -H "Idempotency-Key: 2c8e4f1a-6b3d-4e9a-8c71-5d0f2b7e9a14" \
  --data-raw "$BODY"

A new run returns 202; a request repeated with the same key and the same device returns the same run with 200 and replayed: true. The example shows the data field.

{
  "run": {
    "runId": "01900000-0000-7000-8000-000000000801",
    "deviceId": "00000000-0000-0000-0000-000000000401",
    "environment": "LIVE",
    "source": "MANUAL_API",
    "runStatus": "STARTED",
    "reason": null,
    "businessDate": null,
    "commandId": "01900000-0000-7000-8000-000000000802",
    "commandStatus": "CREATED",
    "deliveryPath": "MQTT",
    "resultState": "PENDING",
    "attemptCount": 1,
    "nextAttemptAt": null,
    "windowEndsAt": null,
    "resultLineCount": 0,
    "completedAt": null,
    "createdAt": "2026-01-02T20:00:00.000Z",
    "updatedAt": "2026-01-02T20:00:00.000Z"
  },
  "replayed": false
}

Before end of day starts, these checks run:

  • The device must be ACTIVE; otherwise 409 physical_pos.payment.terminal_not_payable (details.reason such as status_suspended).
  • The device model must support end of day started by the server; otherwise 422 physical_pos.payment.operation_unsupported (details.reason: settlement_unsupported). For devices connected through the vendor's cloud, end of day from the server is currently disabled (vendor_settlement_report_unsupported). → Connection Methods
  • The device must be connected: 409 physical_pos.payment.device_offline; if the connection state cannot be verified, 503 physical_pos.presence.unavailable.
  • If a payment is running on the device, an uncertain-outcome hold is in place or another end of day is running: 409 physical_pos.payment.device_busy (details.reason: payment_in_progress, unknown_outcome_hold or settlement_in_progress; details.retryAfterSeconds).

If one of these checks rejects the request, no run record is opened. While end of day is running, the device does not take new payments: a payment request gets 409 physical_pos.payment.device_busy (settlement_in_progress). → One active payment per device

202 means end of day has started, not that it has finished. Follow the result through the physical_pos.settlement.completed webhook or the run's resultState field.

List runs

GET /api/v1/physical-pos/settlement-runs · physical_pos:view or physical_pos:payments

Newest run first. The response is { "items": [ … ], "pageInfo": { … } }; each item is a run object.

Query parameterTypeDescription
limitinteger1–100, default 25.
cursorstringpageInfo.nextCursor from the previous response.
deviceIdstring (UUID)Device.
sourcestringMANUAL_API, MANUAL_PANEL or SCHEDULED.
runStatusstringPENDING, STARTED, SKIPPED or FAILED.
createdFromstringLower bound for when the run was opened, ISO 8601 UTC (ends with Z). Default: the last 31 days.
createdTostringUpper bound, same format. Default: now + 5 minutes.
includeTotalbooleanIf true, pageInfo.totalCount is filled on the first page (without cursor).

The time window is at most 93 days. A malformed filter gets 400 physical_pos.input.filter_invalid (details.field).

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/settlement-runs?deviceId=00000000-0000-0000-0000-000000000401&runStatus=FAILED"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Retrieve a run

GET /api/v1/physical-pos/settlement-runs/{runId} · physical_pos:view or physical_pos:payments

The response is { "run": { … } }. A run that does not exist, belongs to another organization or lives in the other environment gets 404 physical_pos.settlement.run_not_found.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/settlement-runs/01900000-0000-7000-8000-000000000801"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

The run object

FieldTypeDescription
runIdstringThe run's ID.
deviceIdstringDevice.
environmentstringLIVE or TEST.
sourcestringWho started the run: MANUAL_API (API), MANUAL_PANEL (panel) or SCHEDULED (scheduled end of day).
runStatusstringSee the table below.
reasonstring | nullWhy the run is waiting, was skipped or failed. See the table below.
businessDatestring | nullBusiness day of a scheduled end of day (YYYY-MM-DD); null on a run started by hand.
commandIdstring | nullThe end-of-day command sent to the device. Matches commandId in End-of-Day Records.
commandStatusstring | nullThe command's state: CREATED, DISPATCHING, DISPATCHED, ACKED, REJECTED, EXPIRED or CANCELLED.
deliveryPathstring | nullHow the command reaches the device; currently MQTT.
resultStatestring | nullThe end-of-day result: PENDING (waiting), COMPLETED (the device reported the result), NOT_COMPLETED (the command was rejected, expired or cancelled and no result arrived). null if there is no command.
attemptCountintegerNumber of start attempts.
nextAttemptAtstring | nullFor scheduled end of day, when the next attempt runs.
windowEndsAtstring | nullFor scheduled end of day, when the attempt window ends.
resultLineCountintegerNumber of bank rows the device reported.
completedAtstring | nullWhen the result was recorded.
createdAt, updatedAtstringCreation and last change.

runStatus:

ValueMeaning
PENDINGA scheduled end of day is waiting for its attempt (first attempt or retry).
STARTEDThe end-of-day command was queued for the device. The result is in resultState. A run started by hand opens with this status.
SKIPPEDEnd of day was deliberately skipped.
FAILEDEnd of day could not be started within the attempt window, or no result arrived.

reason:

ValueMeaning
DEVICE_BUSYAn operation was running on the device; retried.
DEVICE_OFFLINEThe device was not connected.
PRESENCE_UNAVAILABLEThe device's connection state could not be verified; retried.
COMMAND_REJECTED, COMMAND_EXPIREDThe device rejected the command, or the command expired.
RESULT_MISSINGThe device received the command but did not report a result within 30 minutes (FAILED).
WINDOW_EXPIREDThe attempt window ended (FAILED).
SETTLEMENT_UNSUPPORTEDThe device model does not support end of day from the server (SKIPPED).
DEVICE_NOT_ACTIVEThe device is not active (SKIPPED).
DEVICE_NOT_FOUNDThe device no longer exists (SKIPPED).
ALREADY_SETTLEDEnd of day was already taken for that business day (SKIPPED).
POLICY_CHANGEDThe end-of-day policy changed (SKIPPED).
INTERNAL_ERRORUnexpected error; retried.

The value sets are open; ignore values you do not recognise.

Errors

HTTPcodeWhen
400physical_pos.idempotency.key_required · .key_invalidIdempotency-Key missing or malformed (8–200 printable ASCII characters without spaces).
400physical_pos.input.filter_invaliddeviceId is not a UUID, or a list filter is malformed (details.field).
400physical_pos.cursor.invalidcursor is corrupt.
400VALIDATION_ERRORThe start request has a body field.
403physical_pos.environment.test_key_read_onlyStart was made with a test key.
404physical_pos.device.not_foundThe device does not exist, is not yours or lives in the other environment.
404physical_pos.settlement.run_not_foundRun not found.
409physical_pos.payment.terminal_not_payableThe device is not active (details.reason).
409physical_pos.payment.device_offlineThe device is not connected.
409physical_pos.payment.device_busyAn operation is running on the device (details.reason, details.retryAfterSeconds).
409physical_pos.idempotency_mismatchThe key was used for end of day on another device.
422physical_pos.payment.operation_unsupportedsettlement_unsupported or vendor_settlement_report_unsupported.
429RATE_LIMITEDMore than 30 requests per API key in 60 seconds; the counter is shared with end-of-day policy writes. Wait for Retry-After.
503physical_pos.presence.unavailable · physical_pos.signing.unavailableTemporary; retry with the same Idempotency-Key.

All codes: Error Codes.