Physical POS
API Reference
Transactions

Transactions

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.

A transaction is a root payment (a sale, a pre-authorisation or an unmatched refund) together with the reversals linked to it (void, refund, pre-authorisation close and cancel). These endpoints return transactions as trees; for single payment records use the Payments endpoint.

MethodPathScope
GET/api/v1/physical-pos/transactionsphysical_pos:view or physical_pos:payments
GET/api/v1/physical-pos/transactions/ambiguousphysical_pos:view or physical_pos:payments
GET/api/v1/physical-pos/transactions/{paymentId}physical_pos:view or physical_pos:payments
  • The endpoints only read; either scope is enough. There is no Idempotency-Key and no rate limit.
  • Records live in your key's environment: a test key sees only test records, a live key only live records.
  • Fields of the payment object: Payments › Payment object.

List transactions

GET /api/v1/physical-pos/transactions

Each row is a root payment with its reversals; newest root first.

Query parameterTypeDescription
limitintegerTransactions per page, 1–100. Default 25.
cursorstringpageInfo.nextCursor from the previous response.
createdFromstringLower bound of the root's creation time, ISO 8601 UTC (ends with Z, at most 3 decimals). Default: last 31 days.
createdTostringUpper bound, same format. Default: now + 5 minutes.
paymentStatusstringThe root's status. → Statuses
deviceIdstring (UUID)The device that ran the root.
storeIdstring (UUID)The store the device was assigned to at payment time.
registerIdstring (UUID)The register the device was assigned to at payment time.
merchantReferencestringExact match on the root's reference.
amountFromMinorstringLower bound (inclusive) of the root's requested amount, in minor units, 1 or more.
amountToMinorstringUpper bound (inclusive).
originstringAPI or DEVICE_DIRECT (a sale made directly on the device).
operationstringThe root's operation: SALE, PREAUTH_OPEN or REFUND_UNMATCHED.
  • The time window is at most 93 days and createdFrom must be before createdTo; otherwise 400 physical_pos.input.filter_invalid (details.reason: range_invalid). The same reason comes back when amountFromMinor is greater than amountToMinor.
  • Value sets are case-insensitive.
  • The store and register filters use the device's assignment at payment time: if the device is later moved to another store, the transaction stays with the first store.

Response element:

FieldTypeDescription
rootobjectThe root payment.
childrenarrayReversals, oldest first, at most 50.
childrenTruncatedbooleantrue if there are more than 50 reversals; read the transaction detail for all of them.
itemSummaryobject{ lineCount, refundStatus, refundedMinor }: number of item lines, item refund status (NONE, PARTIAL, FULL) and the amount refunded by item refunds. lineCount is 0 on a sale without items.
storeIdstring | nullThe device's store at payment time; null if not assigned.
registerIdstring | nullThe device's register at payment time.

In the list, the items and refundItems arrays of the root and children payments are empty.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/transactions?storeId=00000000-0000-0000-0000-000000000101&operation=SALE"
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"
{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "items": [
      {
        "root": { "paymentId": "01900000-0000-7000-8000-000000000501", "operation": "SALE", "paymentStatus": "APPROVED", "amountMinor": "4500", "reversedMinor": "1500", "reversalStatus": "PARTIALLY_REFUNDED" },
        "children": [
          { "paymentId": "01900000-0000-7000-8000-000000000502", "operation": "REFUND", "paymentStatus": "APPROVED", "amountMinor": "1500", "originalPaymentId": "01900000-0000-7000-8000-000000000501" }
        ],
        "childrenTruncated": false,
        "itemSummary": { "lineCount": 2, "refundStatus": "PARTIAL", "refundedMinor": "1500" },
        "storeId": "00000000-0000-0000-0000-000000000101",
        "registerId": "00000000-0000-0000-0000-000000000201"
      }
    ],
    "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
  },
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

The payment objects are shortened in the example; the response contains every field of the payment object.

Uncertain payments

GET /api/v1/physical-pos/transactions/ambiguous

Lists payments (roots and reversals) in UNKNOWN and MANUAL_REVIEW, newest first. There is no time window: all your uncertain payments are in this list.

Query parameterTypeDescription
limitinteger1–100, default 25.
cursorstringpageInfo.nextCursor from the previous response.
deviceIdstring (UUID)Device.
paymentStatusstringUNKNOWN or MANUAL_REVIEW; any other value gets 400 physical_pos.input.filter_invalid.
includeTotalbooleanWhen true, pageInfo.totalCount is filled on the first page (without cursor) with the number of uncertain payments matching the filters; null on later pages.

The response element is the payment object. A payment with resolvable: true can be resolved in the panel. What to do with an uncertain payment: Uncertain outcome.

Transaction detail

GET /api/v1/physical-pos/transactions/{paymentId}

Returns a transaction's root, all its reversals and its timeline. paymentId can be the root's or a reversal's ID; with a reversal's ID you get the root's tree. This endpoint takes no query parameters.

Transaction: root payment and its reversalsThe root sale is approved for 45000 minor units; a 10000 refund is approved and reflected in reversedMinor; a 5000 refund is in progress and its amount is reserved on the root; the refundable remainder is 35000.Root · SALEapprovedAmountMinor "45000"reversedMinor "10000"reservedMinor "5000"PARTIALLY_REFUNDEDRefund · approved"10000" · APPROVEDrootPaymentId = rootRefund · running"5000" · IN_PROGRESSreserved on rootRefundableremainderapproved − reversed45000 − 10000= 35000LEGENDROOTFINISHEDPENDING
Reversals are separate payment records linked to the root (rootPaymentId). reservedMinor here stands for reversalReservedMinor. A root has at most one pending reversal at a time.
{
  "transaction": {
    "requestedPaymentId": "01900000-0000-7000-8000-000000000502",
    "root": { "paymentId": "01900000-0000-7000-8000-000000000501", "items": [ { "lineNo": 1, "name": "Tea" } ] },
    "children": [ { "paymentId": "01900000-0000-7000-8000-000000000502", "refundItems": [ { "lineNo": 1, "quantityMilli": 1000 } ] } ],
    "timeline": [
      { "kind": "PAYMENT", "paymentId": "01900000-0000-7000-8000-000000000501", "commandId": "01900000-0000-7000-8000-000000000601", "commandType": null, "seq": 1, "eventType": "STATUS_CHANGED", "fromStatus": null, "toStatus": "NOT_STARTED", "reasonCode": null, "source": "API", "actorType": "API_KEY", "evidenceStrength": "NONE", "occurredAt": null, "recordedAt": "2026-01-02T09:00:00.000Z" }
    ],
    "timelineTruncated": false,
    "childrenTruncated": false,
    "storeId": "00000000-0000-0000-0000-000000000101",
    "registerId": "00000000-0000-0000-0000-000000000201"
  }
}

The example shows the data field, and the payment objects are shortened.

FieldTypeDescription
requestedPaymentIdstringThe ID you sent.
rootobjectThe root payment, with its items (items).
childrenarrayReversals, oldest first, at most 50; item refunds include their refundItems array.
childrenTruncatedbooleantrue if there are more than 50 reversals.
timelinearrayPayment and device command events, oldest first. At most 500 rows; if there are more, the newest 500 come back.
timelineTruncatedbooleantrue if the timeline was shortened.
storeId, registerIdstring | nullThe device's store and register at payment time.

Timeline row:

FieldTypeDescription
kindstringPAYMENT (payment event), COMMAND (device command event) or FISCAL_DOCUMENT (fiscal document event).
paymentIdstringThe event's payment.
commandIdstring | nullID of the device command related to the event.
commandTypestring | nullOn a command event, the command's type; null on a payment event.
seqintegerThe event's sequence number in its own record.
eventTypestringThe event's type (e.g. STATUS_CHANGED). The value set is open.
fromStatus, toStatusstring | nullPrevious and new status on a status-changing event.
reasonCodestring | nullThe event's reason. The value set is open; e.g. DEVICE_QUERY_ANSWER_REJECTED: the device's answer to an outcome query could not be verified and was ignored (evidenceStrength: "ADVISORY", the payment does not change).
sourcestringSource of the event (e.g. API, DEVICE, USER, SYSTEM).
actorTypestringType of the party that triggered the event: USER, API_KEY, DEVICE, OPERATOR or SYSTEM.
evidenceStrengthstringStrength of the outcome evidence: DEFINITIVE, ADVISORY or NONE.
occurredAtstring | nullWhen the event happened at its source (if the device reported it).
recordedAtstringWhen the event was recorded.

A transaction that does not exist, belongs to another organization or lives in the other environment gets 404 physical_pos.payment.not_found.

Errors

HTTPcodeWhen
400physical_pos.validation.invalidlimit out of range (details.field: limit).
400physical_pos.cursor.invalidBroken cursor; start again from the first page.
400physical_pos.input.filter_invalidInvalid filter; details.field, and details.reason where relevant (range_invalid, too_long, invalid).
400physical_pos.payment.card_data_rejectedA query parameter name or the merchantReference value looks like card data.
400physical_pos.input.environment_invalidenvironment in the request.
400VALIDATION_ERRORUndefined query parameter.
404physical_pos.payment.not_foundTransaction not found.
500physical_pos.gateway.response_invalidUnexpected response; retry with backoff.

Provider report and scan coverage

GET /api/v1/physical-pos/provider-transactions returns existing report rows; it does not initiate payments. It requires physical_pos:view; the signed API key supplies tenant/environment. The panel counterpart /api/panel/v1/physical-pos/provider-transactions uses the merchant session.

List filters: limit (1–100, default 25), cursor, businessDateFrom, businessDateTo (provider report business day YYYY-MM-DD; the default last 7 days use today in Istanbul; maximum window 93 days), unmatched (only rows outside Lunixi) and includeSandbox (default false). That date window limits the list, not the server's historical scanning. An additive reportCoverage accompanies items and pageInfo:

{
  "items": [],
  "pageInfo": { "hasMore": false, "nextCursor": null },
  "reportCoverage": {
    "status": "PENDING",
    "trackedScopes": 2,
    "pendingDays": 8,
    "waitingFinalityDays": 1,
    "targetBusinessDate": "2026-11-05",
    "completedThrough": "2026-10-15",
    "oldestPendingDate": "2026-10-16"
  }
}

Synthetic example. Coverage spans all tracked scopes independently of page/date/unmatched filters and preserves the includeSandbox choice.

FieldMeaning
statusUNAVAILABLE: no scope tracked yet. PENDING: eligible dates remain incomplete or unplanned. CURRENT: all queued eligible report days through the target are complete.
trackedScopesNumber of organization/environment + account + merchant scopes.
pendingDaysQueued open days whose finality wait has elapsed; excludes unplanned dates. Zero alone does not mean CURRENT.
waitingFinalityDaysQueued dates still waiting for finality.
targetBusinessDateClosed UTC date whose finality wait has elapsed; with default 24 hours this is today minus 2 days.
completedThroughProven contiguous completion across applicable scopes; null if unproven. This is not the planning cursor.
oldestPendingDateEarliest eligible incomplete or unplanned date; otherwise null.

An older backend that does not provide coverage produces reportCoverage: null; never assume CURRENT. CURRENT is not a provider financial completeness/retention guarantee. Re-auditing COMPLETE days, an exact intraday activation boundary, provider timezone/retention confirmation and real SDK acceptance remain open. This addition is verified in the source branch; production rollout is announced separately.

Monitoring provider reports in the panel

Physical POS → Reports → Provider reports requires physical_pos:view. The physical_pos:payments permission alone can read sales/tax summaries, but does not grant provider report access.

  • The card shows the scan target, contiguous completion date, tracked scopes, open days and days awaiting finality. These dates use the UTC scan calendar. The list filter sends the provider business-day value unchanged, without converting it to an ISO instant. Its default window uses today in Istanbul, matching the server.
  • Coverage refreshes separately while the tab is active. List dates, pagination and “Only transactions outside Lunixi” do not narrow global coverage. “Also include sandbox records” expands both the list and coverage to live + sandbox; the default is live only.
  • The last successful panel read is shown. Refreshing, failed or outdated reads cannot advertise a cached CURRENT result as fresh success. Older servers without coverage and inconsistent counters/dates appear as unknown. Neither an empty list nor zero open days establishes a complete scan.
  • The report row ID, provider transaction ID and linked Lunixi payment ID remain distinct. Minor-unit amounts are displayed without floating-point loss. CANDIDATE is only a matching hint; MISMATCH indicates conflicting records. An EXTERNAL row creates no Lunixi payment or charge. A linked payment can be opened separately.

Refresh only refreshes panel reads; it does not start a scan job or payment. Source delivery does not verify a live panel or server deployment.