Start End of Day
- 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:view·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 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.
| Method | Path | Scope |
|---|---|---|
POST | /api/v1/physical-pos/devices/{deviceId}/settlement | physical_pos:payments |
GET | /api/v1/physical-pos/settlement-runs | physical_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.completedwebhook. 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; otherwise409 physical_pos.payment.terminal_not_payable(details.reasonsuch asstatus_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_holdorsettlement_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 parameter | Type | Description |
|---|---|---|
limit | integer | 1–100, default 25. |
cursor | string | pageInfo.nextCursor from the previous response. |
deviceId | string (UUID) | Device. |
source | string | MANUAL_API, MANUAL_PANEL or SCHEDULED. |
runStatus | string | PENDING, STARTED, SKIPPED or FAILED. |
createdFrom | string | Lower bound for when the run was opened, ISO 8601 UTC (ends with Z). Default: the last 31 days. |
createdTo | string | Upper bound, same format. Default: now + 5 minutes. |
includeTotal | boolean | If 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
| Field | Type | Description |
|---|---|---|
runId | string | The run's ID. |
deviceId | string | Device. |
environment | string | LIVE or TEST. |
source | string | Who started the run: MANUAL_API (API), MANUAL_PANEL (panel) or SCHEDULED (scheduled end of day). |
runStatus | string | See the table below. |
reason | string | null | Why the run is waiting, was skipped or failed. See the table below. |
businessDate | string | null | Business day of a scheduled end of day (YYYY-MM-DD); null on a run started by hand. |
commandId | string | null | The end-of-day command sent to the device. Matches commandId in End-of-Day Records. |
commandStatus | string | null | The command's state: CREATED, DISPATCHING, DISPATCHED, ACKED, REJECTED, EXPIRED or CANCELLED. |
deliveryPath | string | null | How the command reaches the device; currently MQTT. |
resultState | string | null | The 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. |
attemptCount | integer | Number of start attempts. |
nextAttemptAt | string | null | For scheduled end of day, when the next attempt runs. |
windowEndsAt | string | null | For scheduled end of day, when the attempt window ends. |
resultLineCount | integer | Number of bank rows the device reported. |
completedAt | string | null | When the result was recorded. |
createdAt, updatedAt | string | Creation and last change. |
runStatus:
| Value | Meaning |
|---|---|
PENDING | A scheduled end of day is waiting for its attempt (first attempt or retry). |
STARTED | The end-of-day command was queued for the device. The result is in resultState. A run started by hand opens with this status. |
SKIPPED | End of day was deliberately skipped. |
FAILED | End of day could not be started within the attempt window, or no result arrived. |
reason:
| Value | Meaning |
|---|---|
DEVICE_BUSY | An operation was running on the device; retried. |
DEVICE_OFFLINE | The device was not connected. |
PRESENCE_UNAVAILABLE | The device's connection state could not be verified; retried. |
COMMAND_REJECTED, COMMAND_EXPIRED | The device rejected the command, or the command expired. |
RESULT_MISSING | The device received the command but did not report a result within 30 minutes (FAILED). |
WINDOW_EXPIRED | The attempt window ended (FAILED). |
SETTLEMENT_UNSUPPORTED | The device model does not support end of day from the server (SKIPPED). |
DEVICE_NOT_ACTIVE | The device is not active (SKIPPED). |
DEVICE_NOT_FOUND | The device no longer exists (SKIPPED). |
ALREADY_SETTLED | End of day was already taken for that business day (SKIPPED). |
POLICY_CHANGED | The end-of-day policy changed (SKIPPED). |
INTERNAL_ERROR | Unexpected error; retried. |
The value sets are open; ignore values you do not recognise.
Errors
| HTTP | code | When |
|---|---|---|
400 | physical_pos.idempotency.key_required · .key_invalid | Idempotency-Key missing or malformed (8–200 printable ASCII characters without spaces). |
400 | physical_pos.input.filter_invalid | deviceId is not a UUID, or a list filter is malformed (details.field). |
400 | physical_pos.cursor.invalid | cursor is corrupt. |
400 | VALIDATION_ERROR | The start request has a body field. |
403 | physical_pos.environment.test_key_read_only | Start was made with a test key. |
404 | physical_pos.device.not_found | The device does not exist, is not yours or lives in the other environment. |
404 | physical_pos.settlement.run_not_found | Run not found. |
409 | physical_pos.payment.terminal_not_payable | The device is not active (details.reason). |
409 | physical_pos.payment.device_offline | The device is not connected. |
409 | physical_pos.payment.device_busy | An operation is running on the device (details.reason, details.retryAfterSeconds). |
409 | physical_pos.idempotency_mismatch | The key was used for end of day on another device. |
422 | physical_pos.payment.operation_unsupported | settlement_unsupported or vendor_settlement_report_unsupported. |
429 | RATE_LIMITED | More than 30 requests per API key in 60 seconds; the counter is shared with end-of-day policy writes. Wait for Retry-After. |
503 | physical_pos.presence.unavailable · physical_pos.signing.unavailable | Temporary; retry with the same Idempotency-Key. |
All codes: Error Codes.