Transactions
- 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.
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.
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/physical-pos/transactions | physical_pos:view or physical_pos:payments |
GET | /api/v1/physical-pos/transactions/ambiguous | physical_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-Keyand 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 parameter | Type | Description |
|---|---|---|
limit | integer | Transactions per page, 1–100. Default 25. |
cursor | string | pageInfo.nextCursor from the previous response. |
createdFrom | string | Lower bound of the root's creation time, ISO 8601 UTC (ends with Z, at most 3 decimals). Default: last 31 days. |
createdTo | string | Upper bound, same format. Default: now + 5 minutes. |
paymentStatus | string | The root's status. → Statuses |
deviceId | string (UUID) | The device that ran the root. |
storeId | string (UUID) | The store the device was assigned to at payment time. |
registerId | string (UUID) | The register the device was assigned to at payment time. |
merchantReference | string | Exact match on the root's reference. |
amountFromMinor | string | Lower bound (inclusive) of the root's requested amount, in minor units, 1 or more. |
amountToMinor | string | Upper bound (inclusive). |
origin | string | API or DEVICE_DIRECT (a sale made directly on the device). |
operation | string | The root's operation: SALE, PREAUTH_OPEN or REFUND_UNMATCHED. |
- The time window is at most 93 days and
createdFrommust be beforecreatedTo; otherwise400 physical_pos.input.filter_invalid(details.reason:range_invalid). The same reason comes back whenamountFromMinoris greater thanamountToMinor. - 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:
| Field | Type | Description |
|---|---|---|
root | object | The root payment. |
children | array | Reversals, oldest first, at most 50. |
childrenTruncated | boolean | true if there are more than 50 reversals; read the transaction detail for all of them. |
itemSummary | object | { 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. |
storeId | string | null | The device's store at payment time; null if not assigned. |
registerId | string | null | The 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 parameter | Type | Description |
|---|---|---|
limit | integer | 1–100, default 25. |
cursor | string | pageInfo.nextCursor from the previous response. |
deviceId | string (UUID) | Device. |
paymentStatus | string | UNKNOWN or MANUAL_REVIEW; any other value gets 400 physical_pos.input.filter_invalid. |
includeTotal | boolean | When 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.
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.
| Field | Type | Description |
|---|---|---|
requestedPaymentId | string | The ID you sent. |
root | object | The root payment, with its items (items). |
children | array | Reversals, oldest first, at most 50; item refunds include their refundItems array. |
childrenTruncated | boolean | true if there are more than 50 reversals. |
timeline | array | Payment and device command events, oldest first. At most 500 rows; if there are more, the newest 500 come back. |
timelineTruncated | boolean | true if the timeline was shortened. |
storeId, registerId | string | null | The device's store and register at payment time. |
Timeline row:
| Field | Type | Description |
|---|---|---|
kind | string | PAYMENT (payment event), COMMAND (device command event) or FISCAL_DOCUMENT (fiscal document event). |
paymentId | string | The event's payment. |
commandId | string | null | ID of the device command related to the event. |
commandType | string | null | On a command event, the command's type; null on a payment event. |
seq | integer | The event's sequence number in its own record. |
eventType | string | The event's type (e.g. STATUS_CHANGED). The value set is open. |
fromStatus, toStatus | string | null | Previous and new status on a status-changing event. |
reasonCode | string | null | The 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). |
source | string | Source of the event (e.g. API, DEVICE, USER, SYSTEM). |
actorType | string | Type of the party that triggered the event: USER, API_KEY, DEVICE, OPERATOR or SYSTEM. |
evidenceStrength | string | Strength of the outcome evidence: DEFINITIVE, ADVISORY or NONE. |
occurredAt | string | null | When the event happened at its source (if the device reported it). |
recordedAt | string | When 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
| HTTP | code | When |
|---|---|---|
400 | physical_pos.validation.invalid | limit out of range (details.field: limit). |
400 | physical_pos.cursor.invalid | Broken cursor; start again from the first page. |
400 | physical_pos.input.filter_invalid | Invalid filter; details.field, and details.reason where relevant (range_invalid, too_long, invalid). |
400 | physical_pos.payment.card_data_rejected | A query parameter name or the merchantReference value looks like card data. |
400 | physical_pos.input.environment_invalid | environment in the request. |
400 | VALIDATION_ERROR | Undefined query parameter. |
404 | physical_pos.payment.not_found | Transaction not found. |
500 | physical_pos.gateway.response_invalid | Unexpected 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.
| Field | Meaning |
|---|---|
status | UNAVAILABLE: no scope tracked yet. PENDING: eligible dates remain incomplete or unplanned. CURRENT: all queued eligible report days through the target are complete. |
trackedScopes | Number of organization/environment + account + merchant scopes. |
pendingDays | Queued open days whose finality wait has elapsed; excludes unplanned dates. Zero alone does not mean CURRENT. |
waitingFinalityDays | Queued dates still waiting for finality. |
targetBusinessDate | Closed UTC date whose finality wait has elapsed; with default 24 hours this is today minus 2 days. |
completedThrough | Proven contiguous completion across applicable scopes; null if unproven. This is not the planning cursor. |
oldestPendingDate | Earliest 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
CURRENTresult 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.
CANDIDATEis only a matching hint;MISMATCHindicates conflicting records. AnEXTERNALrow 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.