Fiziksel POS
Webhook Olayları

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

OlayNe zaman
physical_pos.payment.approvedÖdeme ya da ters işlem (void, iade, ön provizyon kapama ve iptali) onaylandı.
physical_pos.payment.partially_approvedBanka istenenden az tutar onayladı; çekilen tutar approvedAmountMinor.
physical_pos.payment.declinedBanka ya da kart reddetti; ya da sonucu belirsiz ödeme panelde "para çekilmedi" olarak çözüldü.
physical_pos.payment.cancelledCihazda 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.unknownSonuç belirsiz; para çekilmiş olabilir. Ödemeyi yeniden başlatmayın. → Sonucu belirsiz ödeme
physical_pos.payment.manual_reviewSonuç otomatik doğrulanamadı; ödeme panelden çözülür. Ödemeyi yeniden başlatmayın.
physical_pos.payment.device_saleDoğrudan cihazda yapılan bir satış kaydedildi (origin: "DEVICE_DIRECT"). Satış onaylanmış olarak gelir. → Cihazda doğrudan satış
physical_pos.settlement.completedCihaz gün sonu sonucunu bildirdi. → Gün sonu olayları
physical_pos.settlement.failedZamanlanmış gün sonu deneme penceresinde alınamadı.
physical_pos.settlement.skippedZamanlanmış gün sonu atlandı (cihaz desteklemiyor ya da aktif değil).
physical_pos.settlement.overdueSon 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.failedMali belge düzenlenemedi.
physical_pos.fiscal_document.cancelledMali belge iptal edildi.
physical_pos.fiscal_document.action_requiredMali 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.operation ve data.rootPaymentId ile 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 reversalStatus değerini GET /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ız physical_pos.payment.device_sale olayıyla bildirilir; bu satış için physical_pos.payment.approved gönderilmez. Satışın iadesi olağan ödeme olaylarıyla gelir: data.operation REFUND, data.original.origin DEVICE_DIRECT olur.
  • 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
  }
}
AlanAçıklama
idOlayın kimliği; x-lunixi-event-id başlığıyla aynı.
typeOlay tipi.
organizationIdOrganizasyonunuz.
productCodePHYSICAL_POS.
environmentTEST ya da LIVE.
eventVersion, schemaVersionOlayın ve yükün sürümü.
createdAtOlayın gerçekleştiği an.
dataOlayın yükü; aşağıya bakın.

Ödeme olaylarının data alanları

AlanTipAçıklama
paymentIdstringÖdemenin kimliği.
rootPaymentIdstringKökün kimliği; kökte paymentId ile aynı.
originalobject | nullTers 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.
operationstringSALE, PREAUTH_OPEN, REFUND_UNMATCHED, VOID, REFUND, PREAUTH_CLOSE ya da PREAUTH_CANCEL.
paymentStatusstringÖdemenin yeni durumu. → Durumlar
statusReasonstring | nullGeçişin sebebi. → statusReason
amountMinorstringİstenen tutar, dize.
approvedAmountMinorstring | nullOnaylanan tutar, dize; onay yoksa null.
currencystringPara birimi.
installmentCountinteger | nullTaksit sayısı; peşinde null.
deviceIdstringİşlemi yürüten cihaz.
merchantReferencestring | nullKendi referansınız.
tenderobject | nullYalnız cardMasked, cardBrand ve entryMode.
historySeqintegerÖdemenin durum geçmişindeki sıra numarası. → Sıra ve tekrar
resolvedBystring | nullÖdeme panelden çözüldüyse MERCHANT; diğer her durumda null.
cashierobjectÖ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"
}
AlanTipAçıklama
originstringHer zaman DEVICE_DIRECT.
deviceOccurredAtstringSatışı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 operation SALE, paymentStatus APPROVED, rootPaymentId paymentId ile aynı, merchantReference, statusReason ve original null, historySeq 1'dir.
  • Satışın iadesini ters işlem ucuyla yaparsınız. İadenin olaylarında data.rootPaymentId bu olayın paymentId değeridir ve data.original.origin DEVICE_DIRECT olur.
  • Satışı ödeme ve işlem uçlarından da okursunuz: İşlemler.

Mali belge olaylarının data alanları

issued, failed ve cancelled olayları:

AlanTipAçıklama
documentIdstringBelgenin kimliği.
paymentIdstringBelgenin ödemesi.
attemptNointegerBelgenin deneme numarası.
documentTypestringE_ARCHIVE, E_INVOICE, INFO_SLIP, OKC_RECEIPT, EXPENSE_SLIP, FREE_EXPENSE_SLIP, RETURN_SLIP, E_SMM, E_MM ya da OTHER.
fiscalStatusstringBelgenin yeni durumu: ISSUED, FAILED ya da CANCELLED.
statusReasonstring | nullGeçişin sebebi.
documentNumberstring | nullBelge numarası.
documentUuidstring | nullBelgenin evrensel kimliği (e-belgelerde).
issuedAtstring | nullBelgenin düzenlendiği an.
resolvedBystring | nullBelge panelden çözüldüyse MERCHANT.
historySeqintegerBelgenin durum geçmişindeki sıra numarası.

action_required olayı:

AlanTipAçıklama
documentId, paymentId, attemptNo, documentType, fiscalStatus, historySeqYukarıdaki gibi.
actionRequiredbooleanPanelden işlem gerekiyorsa true; gereken işlem kalmadıysa false.
availableActionsstring[]Panelde yapılabilecek işlemlerin kodları.
alarmsstring[]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" }
    }
  ]
}
AlanAçıklama
settlementIdGün sonu kaydının kimliği; sunucudan başlatılan gün sonunda komut kimliği.
runIdGün sonu çalışması; cihazda elle alınan gün sonunda null.
sourceMANUAL_API, MANUAL_PANEL, SCHEDULED ya da DEVICE (cihazda alındı).
lateSonuç geç geldiyse true.
periodFrom, periodToGün sonunun kapsadığı dönem.
deviceClosedAtCihazın bildirdiği kapanış zamanı.
lineCount, mismatchedLineCount, unmappedLineCountBanka 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.historySeq artar: elinizdekinden küçük historySeq taşı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 2xx dönmezse teslimat yeniden denenir: 12 deneme, yaklaşık 52 saat. → Webhook'lar