Physical POS
Webhook Events

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

EventWhen
physical_pos.payment.approvedA payment or a reversal (void, refund, pre-authorisation close and cancel) was approved.
physical_pos.payment.partially_approvedThe bank approved less than requested; the amount taken is approvedAmountMinor.
physical_pos.payment.declinedThe bank or the card declined; or a payment with an uncertain outcome was resolved in the panel as "no money taken".
physical_pos.payment.cancelledA payment that had started on the device was cancelled; no money was taken.
physical_pos.payment.expiredThe 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.failedThe payment could not be started on the device; no money was taken.
physical_pos.payment.unknownThe outcome is uncertain; money may have been taken. Do not start the payment again. → Uncertain outcome
physical_pos.payment.manual_reviewThe outcome could not be verified automatically; the payment is resolved in the panel. Do not start the payment again.
physical_pos.payment.device_saleA sale made directly on the device was recorded (origin: "DEVICE_DIRECT"). The sale arrives already approved. → Sales made on the device
physical_pos.settlement.completedThe device reported an end-of-day result. → End-of-day events
physical_pos.settlement.failedA scheduled end of day could not be taken within the attempt window.
physical_pos.settlement.skippedA scheduled end of day was skipped (the device does not support it or is not active).
physical_pos.settlement.overdueThe alert time set in the policy has passed since the last end of day.
physical_pos.fiscal_document.issuedThe payment's fiscal document was issued (on payments with a fiscal document).
physical_pos.fiscal_document.failedThe fiscal document could not be issued.
physical_pos.fiscal_document.cancelledThe fiscal document was cancelled.
physical_pos.fiscal_document.action_requiredThe 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.operation and data.rootPaymentId.
  • When a reversal completes, no separate event is sent for the root; read the root's current reversalStatus with GET /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 the physical_pos.payment.device_sale event; no physical_pos.payment.approved is sent for it. A refund of that sale comes with the usual payment events: data.operation is REFUND and data.original.origin is DEVICE_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
  }
}
FieldDescription
idThe event's ID; same as the x-lunixi-event-id header.
typeEvent type.
organizationIdYour organization.
productCodePHYSICAL_POS.
environmentTEST or LIVE.
eventVersion, schemaVersionVersion of the event and of the payload.
createdAtWhen the event happened.
dataThe event's payload; see below.

data fields of payment events

FieldTypeDescription
paymentIdstringThe payment's ID.
rootPaymentIdstringThe root's ID; same as paymentId on the root.
originalobject | nullOn 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.
operationstringSALE, PREAUTH_OPEN, REFUND_UNMATCHED, VOID, REFUND, PREAUTH_CLOSE or PREAUTH_CANCEL.
paymentStatusstringThe payment's new status. → Statuses
statusReasonstring | nullReason of the transition. → statusReason
amountMinorstringRequested amount, as a string.
approvedAmountMinorstring | nullApproved amount, as a string; null without an approval.
currencystringCurrency.
installmentCountinteger | nullInstallment count; null for a single payment.
deviceIdstringThe device that ran the operation.
merchantReferencestring | nullYour reference.
tenderobject | nullOnly cardMasked, cardBrand and entryMode.
historySeqintegerSequence number in the payment's status history. → Ordering and duplicates
resolvedBystring | nullMERCHANT if the payment was resolved in the panel; null in every other case.
cashierobjectIf 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"
}
FieldTypeDescription
originstringAlways DEVICE_DIRECT.
deviceOccurredAtstringWhen 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 operation is SALE, paymentStatus is APPROVED, rootPaymentId equals paymentId, merchantReference, statusReason and original are null, and historySeq is 1.
  • You refund the sale with the reversal endpoint. In the refund's events data.rootPaymentId is this event's paymentId and data.original.origin is DEVICE_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:

FieldTypeDescription
documentIdstringThe document's ID.
paymentIdstringThe document's payment.
attemptNointegerThe document's attempt number.
documentTypestringE_ARCHIVE, E_INVOICE, INFO_SLIP, OKC_RECEIPT, EXPENSE_SLIP, FREE_EXPENSE_SLIP, RETURN_SLIP, E_SMM, E_MM or OTHER.
fiscalStatusstringThe document's new status: ISSUED, FAILED or CANCELLED.
statusReasonstring | nullReason of the transition.
documentNumberstring | nullDocument number.
documentUuidstring | nullThe document's universal ID (on e-documents).
issuedAtstring | nullWhen the document was issued.
resolvedBystring | nullMERCHANT if the document was resolved in the panel.
historySeqintegerSequence number in the document's status history.

action_required event:

FieldTypeDescription
documentId, paymentId, attemptNo, documentType, fiscalStatus, historySeqAs above.
actionRequiredbooleantrue if action is needed in the panel; false when no action is left.
availableActionsstring[]Codes of the actions available in the panel.
alarmsstring[]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" }
    }
  ]
}
FieldDescription
settlementIdThe end-of-day record's ID; the command ID when the server started end of day.
runIdThe end-of-day run; null for an end of day taken by hand on the device.
sourceMANUAL_API, MANUAL_PANEL, SCHEDULED or DEVICE (taken on the device).
latetrue if the result arrived late.
periodFrom, periodToThe period the end of day covers.
deviceClosedAtThe closing time the device reported.
lineCount, mismatchedLineCount, unmappedLineCountNumber 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.historySeq increases: an event with a historySeq lower 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