End-of-Day Records
- 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.
GET /api/v1/physical-pos/settlements · scope physical_pos:view or physical_pos:payments
When a POS device takes end-of-day, it reports one line per bank: sale, refund and void counts and amounts. Lunixi compares each line with its own records and lists the result on this endpoint. Records live in your key's environment; the newest end-of-day comes first.
| Query parameter | Type | Description |
|---|---|---|
limit | integer | 1–100, default 25. |
cursor | string | pageInfo.nextCursor from the previous response. Use the cursor as is. |
createdFrom | string | Lower bound of the end-of-day operation's time, ISO 8601 UTC (ends with Z). Default: last 31 days. |
createdTo | string | Upper bound, same format. Default: now + 5 minutes. |
deviceId | string (UUID) | Device. |
lineStatus | string | MATCHED, MISMATCH or UNMAPPED. |
includeTotal | boolean | When true, pageInfo.totalCount is filled on the first page (without cursor) with the number of records matching the filters; null on later pages. |
The time window is at most 93 days; otherwise 400 physical_pos.input.filter_invalid (details.reason: range_invalid).
{
"items": [
{
"commandId": "01900000-0000-7000-8000-000000000701",
"settlementRef": null,
"lineNo": 1,
"deviceId": "00000000-0000-0000-0000-000000000401",
"acquirerCode": "0000",
"acquirerRefRaw": "0000",
"acquirerName": "Example Bank",
"deviceName": "Register 1 POS",
"batchNo": "000123",
"bankTerminalNumber": "PS000001",
"currency": "TRY",
"lineStatus": "MISMATCH",
"reported": { "saleCount": 42, "saleMinor": "189000", "refundCount": 1, "refundMinor": "1500", "voidCount": 0, "voidMinor": "0" },
"system": { "saleCount": 41, "saleMinor": "184500", "refundCount": 1, "refundMinor": "1500", "voidCount": 0, "voidMinor": "0" },
"difference": { "saleCount": 1, "saleMinor": "4500", "refundCount": 0, "refundMinor": "0", "voidCount": 0, "voidMinor": "0" },
"periodFrom": "2026-01-01T20:00:05.000Z",
"periodTo": "2026-01-02T20:00:03.000Z",
"deviceClosedAt": "2026-01-02T20:00:01.000Z",
"recordedAt": "2026-01-02T20:00:04.000Z"
}
],
"pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
}The example shows the data field.
| Field | Type | Description |
|---|---|---|
commandId | string | null | If the end-of-day was taken with an end-of-day command sent by Lunixi, the command's ID; null for an end-of-day started on the device. |
settlementRef | string | null | For an end-of-day started on the device, the end-of-day ID the device gave it; null for an end-of-day taken with a command. Every record has exactly one of commandId and settlementRef. |
lineNo | integer | The device's line number within the end-of-day; numbers may have gaps. |
deviceId | string | The device that took end-of-day. |
acquirerCode | string | null | Four-digit bank code; null if the bank the device reported was not recognised. |
acquirerRefRaw | string | null | The bank code the device reported, as is. When the bank is not recognised (UNMAPPED) this field shows which code was not recognised; it is also filled in on recognised lines. |
acquirerName | string | null | The bank's display name; null if the bank was not recognised. |
deviceName | string | null | The device's current display name (displayName). |
batchNo | string | null | The bank's batch number. |
bankTerminalNumber | string | null | The bank's terminal number (TID). |
currency | string | Currency. |
lineStatus | string | MATCHED: reported and computed totals are equal. MISMATCH: at least one number differs. UNMAPPED: the bank the device reported was not recognised; the line is not compared and the system totals are 0. |
reported | object | Totals the device reported: saleCount, saleMinor, refundCount, refundMinor, voidCount, voidMinor. |
system | object | Totals computed from Lunixi's records, same fields. |
difference | object | Reported − computed, same fields; can be negative. |
periodFrom, periodTo | string | The comparison window. periodFrom is the same device's previous end-of-day (at most 31 days back). |
deviceClosedAt | string | null | The closing time the device reported. |
recordedAt | string | When the end-of-day result was recorded. |
Within reported, system and difference, saleCount, refundCount and voidCount are JSON integers; saleMinor, refundMinor and voidMinor are canonical minor-unit strings. Reported and system amounts are nonnegative; monetary differences may be signed. For UNMAPPED rows, system counts are 0 and system amounts are "0".
The computed total (system) is made of these operations:
- operations on the same device, at the same bank and in the same currency; if a reversal's bank is not known, the sale's bank is used;
- card payments only; cash, QR and meal card payments are not part of the bank's end-of-day;
- operations completed after
periodFromand up toperiodTo(inclusive); for a sale made directly on the device, the sale time the device reported is used; - bucket and amount rules are the same as in reports. → Reports › Common rules
When you see an UNMAPPED line, contact support so the bank can be recognised; pass on the acquirerRefRaw value.
Payments included in an end-of-day can no longer be voided; refund them instead. → Payment Flow › End of day and voids
Errors
| HTTP | code | When |
|---|---|---|
400 | physical_pos.validation.invalid | limit out of range. |
400 | physical_pos.cursor.invalid | Broken cursor. |
400 | physical_pos.input.filter_invalid | Invalid filter; details.field, and details.reason where relevant. |
400 | physical_pos.input.environment_invalid | environment in the request. |
400 | physical_pos.payment.card_data_rejected | A query parameter name looks like card data. |
400 | VALIDATION_ERROR | Undefined query parameter. |
500 | physical_pos.gateway.response_invalid | Unexpected response; retry with backoff. |