Physical POS
API Reference
End-of-Day Records

End-of-Day Records

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.

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 parameterTypeDescription
limitinteger1–100, default 25.
cursorstringpageInfo.nextCursor from the previous response. Use the cursor as is.
createdFromstringLower bound of the end-of-day operation's time, ISO 8601 UTC (ends with Z). Default: last 31 days.
createdTostringUpper bound, same format. Default: now + 5 minutes.
deviceIdstring (UUID)Device.
lineStatusstringMATCHED, MISMATCH or UNMAPPED.
includeTotalbooleanWhen 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.

FieldTypeDescription
commandIdstring | nullIf 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.
settlementRefstring | nullFor 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.
lineNointegerThe device's line number within the end-of-day; numbers may have gaps.
deviceIdstringThe device that took end-of-day.
acquirerCodestring | nullFour-digit bank code; null if the bank the device reported was not recognised.
acquirerRefRawstring | nullThe 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.
acquirerNamestring | nullThe bank's display name; null if the bank was not recognised.
deviceNamestring | nullThe device's current display name (displayName).
batchNostring | nullThe bank's batch number.
bankTerminalNumberstring | nullThe bank's terminal number (TID).
currencystringCurrency.
lineStatusstringMATCHED: 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.
reportedobjectTotals the device reported: saleCount, saleMinor, refundCount, refundMinor, voidCount, voidMinor.
systemobjectTotals computed from Lunixi's records, same fields.
differenceobjectReported − computed, same fields; can be negative.
periodFrom, periodTostringThe comparison window. periodFrom is the same device's previous end-of-day (at most 31 days back).
deviceClosedAtstring | nullThe closing time the device reported.
recordedAtstringWhen 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 periodFrom and up to periodTo (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

HTTPcodeWhen
400physical_pos.validation.invalidlimit out of range.
400physical_pos.cursor.invalidBroken cursor.
400physical_pos.input.filter_invalidInvalid filter; details.field, and details.reason where relevant.
400physical_pos.input.environment_invalidenvironment in the request.
400physical_pos.payment.card_data_rejectedA query parameter name looks like card data.
400VALIDATION_ERRORUndefined query parameter.
500physical_pos.gateway.response_invalidUnexpected response; retry with backoff.