Webhook Olayları
Fiziksel POS, ödemenin ve mali belgenin sonucunu webhook ile bildirir. Teslimat, imza doğrulama ve yeniden deneme bütün ürünlerde aynıdır: Webhook'lar.
Olayları almak için endpoint'inizi panelde Webhook'lar sayfasında Fiziksel POS ürününü seçerek ya da webhook API'sinde productCode: "PHYSICAL_POS" ile oluşturun ve physical_pos.* olaylarına abone edin. → Webhook Kurulumu
Ödeme olayları, ödeme uçları hedef cihazın modeli için çalıştığında gönderilir; yetenek tanımı bulunmayan cihazda ödeme kaydı oluşmadığı için olay da oluşmaz. → Ödeme Akışı Mali belge olayları için yeni sözleşme kaynakta bağlandı; prod yayın ve cihaz/issuer yeteneği açılmadan üretim varmış gibi davranmayın. issued/failed ve yeni alarma bağlı action_required yazımı hazır; otomatik yeniden kesim/iptal yürütmesi açık değildir.
Olaylar
| Olay | Ne zaman |
|---|---|
physical_pos.payment.approved | Ödeme ya da ters işlem (void, iade, ön provizyon kapama ve iptali) onaylandı. |
physical_pos.payment.partially_approved | Banka istenenden az tutar onayladı; çekilen tutar approvedAmountMinor. |
physical_pos.payment.declined | Banka ya da kart reddetti; ya da sonucu belirsiz ödeme panelde "para çekilmedi" olarak çözüldü. |
physical_pos.payment.cancelled | Cihazda başlamış ödeme iptal edildi; para çekilmedi. |
physical_pos.payment.expired | Ödeme cihazda hiç başlamadı: süre doldu ya da komut cihaza ulaşmadan iptal ettiniz. Sebep statusReason alanındadır. |
physical_pos.payment.failed | Ödeme cihazda başlatılamadı; para çekilmedi. |
physical_pos.payment.unknown | Sonuç belirsiz; para çekilmiş olabilir. Ödemeyi yeniden başlatmayın. → Sonucu belirsiz ödeme |
physical_pos.payment.manual_review | Sonuç otomatik doğrulanamadı; ödeme panelden çözülür. Ödemeyi yeniden başlatmayın. |
physical_pos.payment.device_sale | Doğrudan cihazda yapılan bir satış kaydedildi (origin: "DEVICE_DIRECT"). Satış onaylanmış olarak gelir. → Cihazda doğrudan satış |
physical_pos.settlement.completed | Cihaz gün sonu sonucunu bildirdi. → Gün sonu olayları |
physical_pos.settlement.failed | Zamanlanmış gün sonu deneme penceresinde alınamadı. |
physical_pos.settlement.skipped | Zamanlanmış gün sonu atlandı (cihaz desteklemiyor ya da aktif değil). |
physical_pos.settlement.overdue | Son gün sonundan politikadaki uyarı süresi kadar zaman geçti. |
physical_pos.fiscal_document.issued | Ödemenin mali belgesi düzenlendi (mali belge düzenlenen ödemelerde). |
physical_pos.fiscal_document.failed | Mali belge düzenlenemedi. |
physical_pos.fiscal_document.cancelled | Mali belge iptal edildi. |
physical_pos.fiscal_document.action_required | Mali belge için panelden işlem yapmanız gerekiyor (ör. kart ödemesi onaylandı ama belge tamamlanamadı). |
- Ödeme olayı her ödeme kaydı için gönderilir: ters işlemler de aynı olay ailesini kullanır. Kök ile ters işlemi
data.operationvedata.rootPaymentIdile ayırırsınız. - Ters işlem sonuçlandığında kök ödeme için ayrı olay gönderilmez; kökün güncel
reversalStatusdeğeriniGET /payments/{paymentId}ile okuyun. - Ödemenin başlatılması ve cihazda başlaması (
NOT_STARTED,IN_PROGRESS) için webhook gönderilmez. - Doğrudan cihazda yapılan satış (
origin: "DEVICE_DIRECT") yalnızphysical_pos.payment.device_saleolayıyla bildirilir; bu satış içinphysical_pos.payment.approvedgönderilmez. Satışın iadesi olağan ödeme olaylarıyla gelir:data.operationREFUND,data.original.originDEVICE_DIRECTolur. - Eşleşmesiz iade bildirimi webhook değildir; hesap sahibine e-posta ve panel bildirimi olarak gider.
Örnek teslimat
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
}
}| Alan | Açıklama |
|---|---|
id | Olayın kimliği; x-lunixi-event-id başlığıyla aynı. |
type | Olay tipi. |
organizationId | Organizasyonunuz. |
productCode | PHYSICAL_POS. |
environment | TEST ya da LIVE. |
eventVersion, schemaVersion | Olayın ve yükün sürümü. |
createdAt | Olayın gerçekleştiği an. |
data | Olayın yükü; aşağıya bakın. |
Ödeme olaylarının data alanları
| Alan | Tip | Açıklama |
|---|---|---|
paymentId | string | Ödemenin kimliği. |
rootPaymentId | string | Kökün kimliği; kökte paymentId ile aynı. |
original | object | null | Ters işlemde (void, iade, ön provizyon kapama ve iptali) asıl ödeme: { "paymentId": "…", "origin": "API" }. paymentId kökün kimliğidir (rootPaymentId ile aynı); origin asıl ödemenin kaynağıdır: API (API ya da panelden başlatıldı) ya da DEVICE_DIRECT (doğrudan cihazda yapıldı). Kökte null. |
operation | string | SALE, PREAUTH_OPEN, REFUND_UNMATCHED, VOID, REFUND, PREAUTH_CLOSE ya da PREAUTH_CANCEL. |
paymentStatus | string | Ödemenin yeni durumu. → Durumlar |
statusReason | string | null | Geçişin sebebi. → statusReason |
amountMinor | string | İstenen tutar, dize. |
approvedAmountMinor | string | null | Onaylanan tutar, dize; onay yoksa null. |
currency | string | Para birimi. |
installmentCount | integer | null | Taksit sayısı; peşinde null. |
deviceId | string | İşlemi yürüten cihaz. |
merchantReference | string | null | Kendi referansınız. |
tender | object | null | Yalnız cardMasked, cardBrand ve entryMode. |
historySeq | integer | Ödemenin durum geçmişindeki sıra numarası. → Sıra ve tekrar |
resolvedBy | string | null | Ödeme panelden çözüldüyse MERCHANT; diğer her durumda null. |
cashier | object | Ödeme cihazda bir kasiyer oturumunda yapıldıysa { "cashierId": "…", "cashierCode": "…" }; kasiyerin adı yer almaz. Kasiyer yoksa alan hiç gönderilmez. |
API istekleri, API yanıtları ve webhook'lar tutarları kanonik minor-unit dize olarak taşır ("4500"). Aritmetikte kesin tam sayı/ondalık türü kullanın; tutarları kayan noktalı sayıya çevirmeyin. İmzayı yükü ayrıştırmadan veya dönüştürmeden önce özgün ham gövde üzerinde doğrulayın. → Para sözleşmesi
Bankanın onay kodu, RRN, banka kodu, terminal bilgisi ve kalemler webhook'ta yer almaz; bu bilgiler için ödemeyi GET /payments/{paymentId} ile okuyun.
Cihazda doğrudan satış: device_sale
Satış Lunixi'den başlatılmadan doğrudan cihazda yapıldığında ve Lunixi'ye kaydedildiğinde physical_pos.payment.device_sale gönderilir. Satış onaylanmış olarak oluşur; bu satış için başka bir durum olayı gelmez. data, ödeme olaylarının alanlarını ve iki ek alanı taşır:
{
"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"
}| Alan | Tip | Açıklama |
|---|---|---|
origin | string | Her zaman DEVICE_DIRECT. |
deviceOccurredAt | string | Satışın cihazda yapıldığı an (ISO 8601, UTC, milisaniyeli). Cihaz o sırada çevrimdışıysa satış daha sonra kaydedilir; bu an olayın createdAt değerinden önce olabilir. |
- Bu olayda
operationSALE,paymentStatusAPPROVED,rootPaymentIdpaymentIdile aynı,merchantReference,statusReasonveoriginalnull,historySeq1'dir. - Satışın iadesini ters işlem ucuyla yaparsınız. İadenin olaylarında
data.rootPaymentIdbu olayınpaymentIddeğeridir vedata.original.originDEVICE_DIRECTolur. - Satışı ödeme ve işlem uçlarından da okursunuz: İşlemler.
Mali belge olaylarının data alanları
issued, failed ve cancelled olayları:
| Alan | Tip | Açıklama |
|---|---|---|
documentId | string | Belgenin kimliği. |
paymentId | string | Belgenin ödemesi. |
attemptNo | integer | Belgenin deneme numarası. |
documentType | string | E_ARCHIVE, E_INVOICE, INFO_SLIP, OKC_RECEIPT, EXPENSE_SLIP, FREE_EXPENSE_SLIP, RETURN_SLIP, E_SMM, E_MM ya da OTHER. |
fiscalStatus | string | Belgenin yeni durumu: ISSUED, FAILED ya da CANCELLED. |
statusReason | string | null | Geçişin sebebi. |
documentNumber | string | null | Belge numarası. |
documentUuid | string | null | Belgenin evrensel kimliği (e-belgelerde). |
issuedAt | string | null | Belgenin düzenlendiği an. |
resolvedBy | string | null | Belge panelden çözüldüyse MERCHANT. |
historySeq | integer | Belgenin durum geçmişindeki sıra numarası. |
action_required olayı:
| Alan | Tip | Açıklama |
|---|---|---|
documentId, paymentId, attemptNo, documentType, fiscalStatus, historySeq | Yukarıdaki gibi. | |
actionRequired | boolean | Panelden işlem gerekiyorsa true; gereken işlem kalmadıysa false. |
availableActions | string[] | Panelde yapılabilecek işlemlerin kodları. |
alarms | string[] | Belge ile ödeme arasındaki uyuşmazlığın kodları. |
Gün sonu olayları
Gün sonu olayları gün sonu başlatma ve gün sonu politikası ile ilgilidir. Tutarlar minor-unit dize, zamanlar ISO 8601 UTC'dir.
physical_pos.settlement.completed — her gün sonu kaydı için bir kez:
{
"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" }
}
]
}| Alan | Açıklama |
|---|---|
settlementId | Gün sonu kaydının kimliği; sunucudan başlatılan gün sonunda komut kimliği. |
runId | Gün sonu çalışması; cihazda elle alınan gün sonunda null. |
source | MANUAL_API, MANUAL_PANEL, SCHEDULED ya da DEVICE (cihazda alındı). |
late | Sonuç geç geldiyse true. |
periodFrom, periodTo | Gün sonunun kapsadığı dönem. |
deviceClosedAt | Cihazın bildirdiği kapanış zamanı. |
lineCount, mismatchedLineCount, unmappedLineCount | Banka satırı sayısı, farklı ve eşleşmeyen satırlar. |
lines[] | Banka satırları: acquirerCode (tanınmayan bankada null), lineStatus (MATCHED, MISMATCH, UNMAPPED), cihazın bildirdiği (reported) ve Lunixi'nin hesapladığı (system) adet ve tutarlar. Ayrıntı: Gün Sonu Kayıtları. |
physical_pos.settlement.failed — zamanlanmış gün sonu alınamadığında, cihaz ve iş günü başına bir kez:
{ "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 ya da INTERNAL_ERROR. source her zaman SCHEDULED'dır.
physical_pos.settlement.skipped — zamanlanmış gün sonu atlandığında:
{ "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 (cihaz sunucudan gün sonunu desteklemiyor) ya da DEVICE_NOT_ACTIVE.
physical_pos.settlement.overdue — son gün sonundan politikadaki overdueAlertHours kadar zaman geçtiğinde, cihaz ve iş günü başına bir kez:
{ "deviceId": "00000000-0000-0000-0000-000000000401", "businessDate": "2026-01-02", "thresholdHours": 26, "settlementMode": "SCHEDULED", "detectedAt": "2026-01-02T22:31:00.000Z" }İmza doğrulama
Her teslimat imzalıdır. İmza, ham gövde üzerinden HMAC-SHA256(secret, "{eventId}.{timestamp}.{rawBody}") ile hesaplanır ve x-lunixi-signature başlığında v2=<hex> olarak gelir; secret rotasyonundan sonraki 24 saat içinde başlıkta ikinci bir v2= öğesi bulunur. Gövdeyi ayrıştırmadan doğrulayın, imzalardan herhangi biri eşleşirse istek geçerlidir. Doğrulama kodu ve zaman damgası toleransı: Webhook'lar.
SDK'lar imzayı ve zaman damgasını doğrular, sonra olayı okur; imza tutmazsa hata fırlatır. Gövdeyi ayrıştırmadan, ham hâliyle verin.
const { parsePhysicalPosWebhookEvent } = require('@lunixi/node-sdk');
// rawBody: gövdenin ham baytları (Buffer ya da string), headers: istek başlıkları
const event = parsePhysicalPosWebhookEvent(rawBody, headers, process.env.LUNIXI_WEBHOOK_SECRET);
// İmza tutmazsa hata fırlatır; olayı id ile tekilleştirin, historySeq ile sıralayın.
console.log(event.id, event.type, event.data.paymentId, event.historySeq);Sıra ve tekrar
- Teslimat sırası garanti değildir. Aynı ödemenin olaylarında
data.historySeqartar: elinizdekinden küçükhistorySeqtaşıyan olay eski bir olaydır, yok sayın. - Aynı olay birden çok kez teslim edilebilir.
id(x-lunixi-event-id) ile tekilleştirin: aynı geçiş her denemede aynı kimliği taşır. - Şüphe duyduğunuz her durumda ödemenin güncel hâlini
GET /payments/{paymentId}ile okuyun. - Endpoint'iniz
2xxdönmezse teslimat yeniden denenir: 12 deneme, yaklaşık 52 saat. → Webhook'lar