Webhook Events
Physical POS reports the outcome of payments and fiscal documents by webhook. Delivery, signature verification and retries are the same across products: Webhooks.
To receive the events, create your endpoint in the panel on the Webhooks page by choosing the Physical POS product, or with productCode: "PHYSICAL_POS" in the webhook API, and subscribe it to physical_pos.* events. → Webhook Setup
Payment events are sent when the payment endpoints work for the target device's model; on a device without a capability definition no payment record is created, so no event is created either. → Payment Flow The new fiscal contract wires event persistence in source; production release and issuer capability enablement are separate. issued/failed and new-alarm action_required writes are ready; automatic reissuance/cancellation execution is not enabled.
Events
| Event | When |
|---|---|
physical_pos.payment.approved | A payment or a reversal (void, refund, pre-authorisation close and cancel) was approved. |
physical_pos.payment.partially_approved | The bank approved less than requested; the amount taken is approvedAmountMinor. |
physical_pos.payment.declined | The bank or the card declined; or a payment with an uncertain outcome was resolved in the panel as "no money taken". |
physical_pos.payment.cancelled | A payment that had started on the device was cancelled; no money was taken. |
physical_pos.payment.expired | The payment never started on the device: the time ran out or you cancelled before the command reached the device. The reason is in statusReason. |
physical_pos.payment.failed | The payment could not be started on the device; no money was taken. |
physical_pos.payment.unknown | The outcome is uncertain; money may have been taken. Do not start the payment again. → Uncertain outcome |
physical_pos.payment.manual_review | The outcome could not be verified automatically; the payment is resolved in the panel. Do not start the payment again. |
physical_pos.payment.device_sale | A sale made directly on the device was recorded (origin: "DEVICE_DIRECT"). The sale arrives already approved. → Sales made on the device |
physical_pos.settlement.completed | The device reported an end-of-day result. → End-of-day events |
physical_pos.settlement.failed | A scheduled end of day could not be taken within the attempt window. |
physical_pos.settlement.skipped | A scheduled end of day was skipped (the device does not support it or is not active). |
physical_pos.settlement.overdue | The alert time set in the policy has passed since the last end of day. |
physical_pos.fiscal_document.issued | The payment's fiscal document was issued (on payments with a fiscal document). |
physical_pos.fiscal_document.failed | The fiscal document could not be issued. |
physical_pos.fiscal_document.cancelled | The fiscal document was cancelled. |
physical_pos.fiscal_document.action_required | The fiscal document needs action in the panel (e.g. the card payment was approved but the document could not be completed). |
- A payment event is sent for every payment record: reversals use the same event family. Tell a root from a reversal with
data.operationanddata.rootPaymentId. - When a reversal completes, no separate event is sent for the root; read the root's current
reversalStatuswithGET /payments/{paymentId}. - No webhook is sent when a payment is started or starts on the device (
NOT_STARTED,IN_PROGRESS). - A sale made directly on the device (
origin: "DEVICE_DIRECT") is reported only with thephysical_pos.payment.device_saleevent; nophysical_pos.payment.approvedis sent for it. A refund of that sale comes with the usual payment events:data.operationisREFUNDanddata.original.originisDEVICE_DIRECT. - The unmatched refund notification is not a webhook; it goes to the account owner as an e-mail and a panel notification.
Example delivery
POST /webhooks/lunixi HTTP/1.1
content-type: application/json
user-agent: Lunixi-Webhook-Service/1.0
x-lunixi-event-id: 00000000-0000-0000-0000-00000000e101
x-lunixi-event-type: physical_pos.payment.approved
x-lunixi-signature: v2=9f2c1a…
x-lunixi-signature-timestamp: 2026-01-02T09:00:21.118Z{
"id": "00000000-0000-0000-0000-00000000e101",
"type": "physical_pos.payment.approved",
"sourceService": "physical-pos-service",
"organizationId": "00000000-0000-0000-0000-00000000000a",
"productCode": "PHYSICAL_POS",
"environment": "LIVE",
"eventVersion": 1,
"schemaVersion": "v1",
"createdAt": "2026-01-02T09:00:20.000Z",
"data": {
"paymentId": "01900000-0000-7000-8000-000000000501",
"rootPaymentId": "01900000-0000-7000-8000-000000000501",
"original": null,
"operation": "SALE",
"paymentStatus": "APPROVED",
"statusReason": "DEVICE_RESULT_APPROVED",
"amountMinor": "4500",
"approvedAmountMinor": "4500",
"currency": "TRY",
"installmentCount": null,
"deviceId": "00000000-0000-0000-0000-000000000401",
"merchantReference": "ORD-2026-000123",
"tender": { "cardMasked": "454360******1234", "cardBrand": "VISA", "entryMode": "CONTACTLESS" },
"historySeq": 4,
"resolvedBy": null
}
}| Field | Description |
|---|---|
id | The event's ID; same as the x-lunixi-event-id header. |
type | Event type. |
organizationId | Your organization. |
productCode | PHYSICAL_POS. |
environment | TEST or LIVE. |
eventVersion, schemaVersion | Version of the event and of the payload. |
createdAt | When the event happened. |
data | The event's payload; see below. |
data fields of payment events
| Field | Type | Description |
|---|---|---|
paymentId | string | The payment's ID. |
rootPaymentId | string | The root's ID; same as paymentId on the root. |
original | object | null | On a reversal (void, refund, pre-authorisation close and cancel), the original payment: { "paymentId": "…", "origin": "API" }. paymentId is the root's ID (same as rootPaymentId); origin is where the original payment came from: API (started through the API or the panel) or DEVICE_DIRECT (made directly on the device). null on the root. |
operation | string | SALE, PREAUTH_OPEN, REFUND_UNMATCHED, VOID, REFUND, PREAUTH_CLOSE or PREAUTH_CANCEL. |
paymentStatus | string | The payment's new status. → Statuses |
statusReason | string | null | Reason of the transition. → statusReason |
amountMinor | string | Requested amount, as a string. |
approvedAmountMinor | string | null | Approved amount, as a string; null without an approval. |
currency | string | Currency. |
installmentCount | integer | null | Installment count; null for a single payment. |
deviceId | string | The device that ran the operation. |
merchantReference | string | null | Your reference. |
tender | object | null | Only cardMasked, cardBrand and entryMode. |
historySeq | integer | Sequence number in the payment's status history. → Ordering and duplicates |
resolvedBy | string | null | MERCHANT if the payment was resolved in the panel; null in every other case. |
cashier | object | If the payment was made on the device in a cashier session, { "cashierId": "…", "cashierCode": "…" }; the cashier's name is not included. If there is no cashier, the field is not sent at all. |
API requests, API responses and webhooks all carry amounts as canonical minor-unit strings ("4500"). Use an exact integer/decimal type for arithmetic; do not convert amounts to floating-point numbers. Verify the signature over the original raw body before parsing or transforming the payload. → Money contract
The bank's authorisation code, RRN, bank code, terminal details and items are not in the webhook; read the payment with GET /payments/{paymentId} for them.
Sales made on the device: device_sale
When a sale is made directly on the device, without being started from Lunixi, and is recorded in Lunixi, physical_pos.payment.device_sale is sent. The sale is created already approved; no other status event comes for it. data carries the payment event fields and two more fields:
{
"paymentId": "01900000-0000-7000-8000-000000000601",
"rootPaymentId": "01900000-0000-7000-8000-000000000601",
"original": null,
"operation": "SALE",
"paymentStatus": "APPROVED",
"statusReason": null,
"amountMinor": "4500",
"approvedAmountMinor": "4500",
"currency": "TRY",
"installmentCount": null,
"deviceId": "00000000-0000-0000-0000-000000000401",
"merchantReference": null,
"tender": { "cardMasked": "454360******1234", "cardBrand": "VISA", "entryMode": "CONTACTLESS" },
"historySeq": 1,
"resolvedBy": null,
"origin": "DEVICE_DIRECT",
"deviceOccurredAt": "2026-01-02T18:42:10.123Z"
}| Field | Type | Description |
|---|---|---|
origin | string | Always DEVICE_DIRECT. |
deviceOccurredAt | string | When the sale was made on the device (ISO 8601, UTC, with milliseconds). If the device was offline at the time, the sale is recorded later; this moment can be earlier than the event's createdAt. |
- In this event
operationisSALE,paymentStatusisAPPROVED,rootPaymentIdequalspaymentId,merchantReference,statusReasonandoriginalarenull, andhistorySeqis1. - You refund the sale with the reversal endpoint. In the refund's events
data.rootPaymentIdis this event'spaymentIdanddata.original.originisDEVICE_DIRECT. - You can also read the sale from the payment and transaction endpoints: Transactions.
data fields of fiscal document events
issued, failed and cancelled events:
| Field | Type | Description |
|---|---|---|
documentId | string | The document's ID. |
paymentId | string | The document's payment. |
attemptNo | integer | The document's attempt number. |
documentType | string | E_ARCHIVE, E_INVOICE, INFO_SLIP, OKC_RECEIPT, EXPENSE_SLIP, FREE_EXPENSE_SLIP, RETURN_SLIP, E_SMM, E_MM or OTHER. |
fiscalStatus | string | The document's new status: ISSUED, FAILED or CANCELLED. |
statusReason | string | null | Reason of the transition. |
documentNumber | string | null | Document number. |
documentUuid | string | null | The document's universal ID (on e-documents). |
issuedAt | string | null | When the document was issued. |
resolvedBy | string | null | MERCHANT if the document was resolved in the panel. |
historySeq | integer | Sequence number in the document's status history. |
action_required event:
| Field | Type | Description |
|---|---|---|
documentId, paymentId, attemptNo, documentType, fiscalStatus, historySeq | As above. | |
actionRequired | boolean | true if action is needed in the panel; false when no action is left. |
availableActions | string[] | Codes of the actions available in the panel. |
alarms | string[] | Codes of the mismatch between the document and the payment. |
End-of-day events
End-of-day events relate to starting end of day and the end-of-day policy. Amounts are minor-unit strings, times are ISO 8601 UTC.
physical_pos.settlement.completed — once per end-of-day record:
{
"settlementId": "01900000-0000-7000-8000-000000000802",
"runId": "01900000-0000-7000-8000-000000000801",
"deviceId": "00000000-0000-0000-0000-000000000401",
"source": "MANUAL_API",
"late": false,
"periodFrom": "2026-01-01T20:31:12.000Z",
"periodTo": "2026-01-02T20:00:40.000Z",
"deviceClosedAt": "2026-01-02T20:00:39.000Z",
"recordedAt": "2026-01-02T20:00:41.000Z",
"lineCount": 1,
"mismatchedLineCount": 1,
"unmappedLineCount": 0,
"lines": [
{
"lineNo": 1,
"acquirerCode": "0000",
"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" }
}
]
}| Field | Description |
|---|---|
settlementId | The end-of-day record's ID; the command ID when the server started end of day. |
runId | The end-of-day run; null for an end of day taken by hand on the device. |
source | MANUAL_API, MANUAL_PANEL, SCHEDULED or DEVICE (taken on the device). |
late | true if the result arrived late. |
periodFrom, periodTo | The period the end of day covers. |
deviceClosedAt | The closing time the device reported. |
lineCount, mismatchedLineCount, unmappedLineCount | Number of bank rows, rows with a difference and unmatched rows. |
lines[] | Bank rows: acquirerCode (null for an unrecognised bank), lineStatus (MATCHED, MISMATCH, UNMAPPED), and the counts and amounts the device reported (reported) and Lunixi calculated (system). Details: End-of-Day Records. |
physical_pos.settlement.failed — when a scheduled end of day could not be taken, once per device and business day:
{ "runId": "01900000-0000-7000-8000-000000000803", "deviceId": "00000000-0000-0000-0000-000000000401", "source": "SCHEDULED", "businessDate": "2026-01-02", "reason": "DEVICE_OFFLINE", "attemptCount": 7, "windowEndsAt": "2026-01-02T22:30:00.000Z", "failedAt": "2026-01-02T22:28:00.000Z" }reason: WINDOW_EXPIRED, DEVICE_OFFLINE, DEVICE_BUSY, PRESENCE_UNAVAILABLE, COMMAND_REJECTED, COMMAND_EXPIRED, RESULT_MISSING or INTERNAL_ERROR. source is always SCHEDULED.
physical_pos.settlement.skipped — when a scheduled end of day is skipped:
{ "runId": "01900000-0000-7000-8000-000000000804", "deviceId": "00000000-0000-0000-0000-000000000402", "businessDate": "2026-01-02", "reason": "SETTLEMENT_UNSUPPORTED", "skippedAt": "2026-01-02T20:30:01.000Z" }reason: SETTLEMENT_UNSUPPORTED (the device does not support end of day from the server) or DEVICE_NOT_ACTIVE.
physical_pos.settlement.overdue — when overdueAlertHours from the policy have passed since the last end of day, once per device and business day:
{ "deviceId": "00000000-0000-0000-0000-000000000401", "businessDate": "2026-01-02", "thresholdHours": 26, "settlementMode": "SCHEDULED", "detectedAt": "2026-01-02T22:31:00.000Z" }Signature verification
Every delivery is signed. The signature is HMAC-SHA256(secret, "{eventId}.{timestamp}.{rawBody}") over the raw body and comes in the x-lunixi-signature header as v2=<hex>; for 24 hours after a secret rotation the header carries a second v2= element. Verify without parsing the body; the request is valid if any of the signatures matches. Verification code and the timestamp tolerance: Webhooks.
The SDKs verify the signature and timestamp, then read the event; they throw if the signature does not match. Pass the body raw, before parsing it.
const { parsePhysicalPosWebhookEvent } = require('@lunixi/node-sdk');
// rawBody: the raw body bytes (Buffer or string), headers: the request headers
const event = parsePhysicalPosWebhookEvent(rawBody, headers, process.env.LUNIXI_WEBHOOK_SECRET);
// Throws if the signature does not match; deduplicate by id, order by historySeq.
console.log(event.id, event.type, event.data.paymentId, event.historySeq);Ordering and duplicates
- Delivery order is not guaranteed. Within the events of one payment,
data.historySeqincreases: an event with ahistorySeqlower than the one you have is an old event; ignore it. - The same event can be delivered more than once. Deduplicate by
id(x-lunixi-event-id): the same transition carries the same ID on every attempt. - Whenever in doubt, read the payment's current state with
GET /payments/{paymentId}. - If your endpoint does not return
2xx, the delivery is retried: 12 attempts over about 52 hours. → Webhooks