Fiziksel POS
Ödeme Akışı

Ödeme Akışı

Fiziksel POS'ta ödemeyi kendi sunucunuzdan başlatırsınız; kart, mağazadaki POS cihazında okunur. Lunixi ödeme komutunu imzalayıp cihaza iletir, cihazdan gelen sonucu kaydeder ve sonucu size webhook ile bildirir. Bu sayfa ödemenin yaşam döngüsünü anlatır: durumlar, ters işlemler, sonucu belirsiz ödeme ve gün sonu.

Akış

Ödeme başlatma sırasıSunucunuz ödemeyi başlatır ve 202 alır; Lunixi imzalı komutu cihaza gönderir; cihaz kartı okuyup bankadan provizyon alır ve sonucu Lunixi'ye bildirir; Lunixi sonucu webhook ile sunucunuza gönderir.POST /payments202 NOT_STARTEDİMZALI KOMUTKARTONAY / RETSONUÇWEBHOOKSunucunuzLunixiPOS cihazıBanka202 "kabul edildi" demektir, "ödendi" değil.
Kesik çizgiler yanıttır. Sonucu webhook ile alın; beklemek istemezseniz ödemeyi sorgulayın.
  • Kabul: Başlatma isteği 202 Accepted ile kabul edilir ve ödeme NOT_STARTED durumunda açılır. Bu yanıt "ödeme kabul edildi" demektir, "ödendi" demek değildir.
  • Cihazda: Cihaz ödemeyi başlattığında ödeme IN_PROGRESS olur: cihaz kartı ya da banka cevabını bekler.
  • Sonuç: Sonuç geldiğinde ödeme son durumlarından birine geçer ve physical_pos.payment.* webhook'u gönderilir. → Webhook Olayları
  • İzleme: Sonucu webhook ile ya da ödemeyi okuyarak izlersiniz. → Ödeme Başlatma › Sonucu alın

Void, iade ve ön provizyon kapama gibi ters işlemler de aynı akışla yürür: her ters işlem asıl ödemeye bağlı yeni bir ödeme kaydı (çocuk ödeme) açar ve kendi sonucunu alır.

Ödeme başlatma ve ters işlem, hedef cihazın modeli için ödeme yetenek tanımı bulunduğunda yürür. Yetenek tanımı bulunmayan cihazda istek, cihaz bulunduktan, terminal bağı ve haberleşme kanalı denetlendikten sonra 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) alır; ödeme kaydı oluşmaz.

Ödeme durumları

Ödeme yaşam döngüsüÖdeme NOT_STARTED olarak açılır, cihazda IN_PROGRESS olur ve onay, ret ya da iptalle son durumuna geçer; hiç başlamazsa EXPIRED ya da FAILED olur; sonuç gelmezse UNKNOWN olur, kanıt gelirse son duruma geçer, gelmezse MANUAL_REVIEW olur ve panelde çözülür.SON DURUMBAŞLADIONAYRET / İPTALSÜRE / RETSONUÇ YOK~10 DKKANIT GELİRSEPANELDE ÇÖZÜMNOT_STARTED202 · kayıt açıldıIN_PROGRESScihaz başlattıAPPROVED ·PARTIALLY_APPROVEDDECLINED ·CANCELLEDEXPIRED · FAILEDcihazda başlamadıUNKNOWNpara çekilmiş olabilirMANUAL_REVIEWpanelden çözülürLEJANTSÜRÜYORDİKKATBİTTİSİZ ÇÖZERSİNİZ
Para yalnız APPROVED ve PARTIALLY_APPROVED durumunda çekilmiştir. UNKNOWN başarısızlık değildir: para çekilmiş olabilir, ödemeyi yeniden başlatmayın.

paymentStatus ödemenin para açısından ne durumda olduğunu söyler. Kararlarınızı yalnız bu alana göre verin.

DurumAnlamıSon durum mu?
NOT_STARTEDÖdeme kaydı açıldı, cihaz ödemeyi henüz başlatmadı.Hayır
IN_PROGRESSCihaz ödemeyi başlattı; kart ya da banka cevabı bekleniyor.Hayır
APPROVEDPara çekildi. Ters işlemde: void, iade ya da kapama gerçekleşti.Evet
PARTIALLY_APPROVEDPara çekildi ama istenenden az; çekilen tutar approvedAmountMinor.Evet
DECLINEDBanka ya da kart reddetti; para çekilmedi.Evet
CANCELLEDÖdeme cihazda başlamıştı ve iptal edildi; para çekilmedi.Evet
EXPIREDÖdeme cihazda hiç başlamadı: süre doldu ya da komut cihaza ulaşmadan iptal ettiniz. Para çekilmedi.Evet
FAILEDÖdeme cihazda hiç başlamadı: cihaz komutu reddetti. Para çekilmedi.Evet
UNKNOWNSonuç bilinmiyor; para çekilmiş olabilir. Sonuç otomatik olarak doğrulanıyor. → Sonucu belirsiz ödemeHayır
MANUAL_REVIEWSonuç otomatik doğrulamayla netleşmedi; ödeme panelden çözülür. → Sonucu belirsiz ödemeHayır
  • Son duruma geçen ödemenin durumu değişmez. Sonradan farklı bir sonuç kanıtı gelirse durum korunur, ödemede outcomeConflict: true olur ve bu kanıt için webhook gönderilmez. outcomeConflict: true gördüğünüzde ödemeyi panelde inceleyin.
  • Zaman aşımı başarısızlık değildir. Sonuç resultDeadlineAt anına kadar gelmezse ödeme DECLINED değil UNKNOWN olur.

Ters işlem durumu: reversalStatus

Asıl ödemede (kökte) ters işlemlerin toplam etkisini gösterir:

DeğerAnlamı
NONETers işlem yok.
PARTIALLY_REFUNDEDKısmi iade yapıldı; yeni iade yapılabilir.
REFUNDEDTamamı iade edildi.
VOIDEDVoid edildi.
PREAUTH_CLOSEDÖn provizyon kapandı (tutar tahsil edildi).
PREAUTH_CANCELLEDÖn provizyon iptal edildi.
PREAUTH_EXPIREDÖn provizyonun süresi doldu.

VOIDED, REFUNDED, PREAUTH_CANCELLED ve PREAUTH_EXPIRED durumundaki ödemeye yeni ters işlem yapılmaz. Ters işlem sonuçlandığında asıl ödeme için ayrı webhook gönderilmez; asıl ödemenin güncel reversalStatus değerini GET /payments/{paymentId} ile okuyun.

Kart sonucu: tender.tenderStatus

PENDING, APPROVED, PARTIALLY_APPROVED, DECLINED, CANCELLED ya da UNKNOWN. İptal edilen, süresi dolan ya da cihazda başlamayan ödemede tenderStatus PENDING kalabilir; ödemenin sonucu için paymentStatus'a bakın.

Durum sebebi: statusReason

statusReason son geçişin makine okunur sebebidir. Değer kümesi açıktır ve yeni değerler eklenebilir: tanımadığınız değeri yok sayın ve kararınızı paymentStatus'a göre verin. Eylem gerektirebilecek değerler:

DeğerAnlamı
MERCHANT_CANCELLED_BEFORE_DISPATCHÖdemeyi komut cihaza ulaşmadan iptal ettiniz (EXPIRED).
COMMAND_EXPIRED_BEFORE_DISPATCHBaşlatma süresi komut cihaza ulaşmadan doldu (EXPIRED). Cihazın ödemeye hazır olduğunu kontrol edip yeni ödeme başlatabilirsiniz. → Cihazın ödemeye hazır olması
COMMAND_DELIVERY_UNKNOWNKomutun cihaza ulaşıp ulaşmadığı doğrulanamadı (UNKNOWN). Ödemeyi yeniden başlatmayın.
RESULT_DEADLINE_PASSEDSonuç süresi içinde gelmedi (UNKNOWN). Ödemeyi yeniden başlatmayın.
UNKNOWN_HOLD_EXPIREDSonuç bekleme süresinde netleşmedi; ödeme incelemeye alındı (MANUAL_REVIEW).
DEVICE_REJECTED_<kod>Cihaz komutu reddetti (FAILED). Ör. DEVICE_REJECTED_ORIGINAL_NOT_FOUND: cihaz ters işlemin asıl işlemini bulamadı.
MERCHANT_RESOLVED_<durum>, MERCHANT_RESOLVED_NOT_CHARGEDÖdeme panelden kanıtla çözüldü.
PROVIDER_CODE_EXPIREDYemek kartı kodunun süresi doldu, ödeme yapılmadı (EXPIRED).
PROVIDER_CODE_WINDOW_ELAPSEDYemek kartı ödemesinin sonucu sorgu süresinde kesinleşmedi (UNKNOWN). Ödemeyi yeniden başlatmayın.
VENDOR_RESULT_<durum>Sonuç cihaz üreticisinin bulutundan geldi. <durum>: APPROVED, PARTIALLY_APPROVED, DECLINED ya da CANCELLED.
VENDOR_REJECTEDCihaz üreticisinin bulutu ödeme isteğini reddetti (FAILED).
VENDOR_SUBMIT_INDETERMINATE, VENDOR_RESULT_INVALIDİsteğin üretici bulutuna ulaşıp ulaşmadığı ya da sonucu doğrulanamadı (UNKNOWN). Ödemeyi yeniden başlatmayın.

Sonucu belirsiz ödeme: UNKNOWN ve MANUAL_REVIEW

🚫

Sonucu belirsiz ödemeyi yeniden başlatmayın. UNKNOWN durumunda para çekilmiş olabilir. Lunixi belirsiz ödemeyi hiçbir zaman otomatik olarak yeniden tahsil etmez. Aynı satış için yeni ödeme başlatırsanız müşteriniz iki kez ödeme yapmış olabilir.

  1. Ödeme UNKNOWN olduğunda physical_pos.payment.unknown webhook'u gönderilir. Bu olayın anlamı "tekrar tahsil etmeyin, sonuç doğrulanıyor"dur.
  2. Cihaz bu sürede (varsayılan 10 dakika) yeni ödeme almaz: aynı cihaza başlatılan ödeme 409 physical_pos.payment.device_busy (details.reason: unknown_outcome_hold, details.retryAfterSeconds) alır.
  3. Sonuç bu sürede kesinleşirse ödeme son durumuna geçer ve ilgili webhook gönderilir.
  4. Sonuç netleşmezse ödeme MANUAL_REVIEW olur, physical_pos.payment.manual_review webhook'u gönderilir ve cihaz yeniden ödeme alabilir. Sonuç arka planda 7 güne kadar sorgulanmaya devam eder.
  5. MANUAL_REVIEW durumundaki ödemeyi panelden kanıtla çözersiniz: banka ekstresi, üretici portalı, gün sonu raporu, cihaz fişi ya da açıklamalı başka bir kanıt. "Para çekildi" kararı bankanın onay kodunu ya da RRN değerini ister. Ödemede resolvable: true ise ödeme panelden çözülebilir. Bu işlemin API ucu yoktur.
  6. Panelde çözülen ödeme son durumuna geçer; webhook yükünde resolvedBy: "MERCHANT" bulunur.

Belirsiz durumdaki ödemede iptal 409 physical_pos.payment.not_cancellable (details.reason: outcome_unknown), ters işlem 409 physical_pos.payment.not_reversible (details.reason: root_not_approved) alır. Belirsiz ödemelerinizin listesi: İşlemler › Sonucu belirsiz ödemeler.

Gün sonu ve void

Gün sonu alınmış ödemeye void yapılamaz; tutarı aynı ödemeye iade ile geri ödersiniz. Ayrıntı ve hangi ters işlemin ne zaman kullanılacağı: Gün Sonu, İptal ve İade.

Cihazda doğrudan satış

Satış, Lunixi'den başlatılmadan doğrudan cihazda da yapılabilir. Bu satış origin: "DEVICE_DIRECT" ile kaydedilir ve onaylanmış olarak oluşur.

Cihaz başına tek aktif ödeme

Bir cihaz aynı anda tek ödeme yürütür. NOT_STARTED, IN_PROGRESS ya da UNKNOWN durumundaki ödeme cihazı tutar; MANUAL_REVIEW cihazı bırakır. Meşgul cihaza başlatılan ödeme 409 physical_pos.payment.device_busy alır:

details.reasonAnlamı
payment_in_progressCihazda yürüyen bir ödeme var.
unknown_outcome_holdCihazdaki bir ödemenin sonucu belirsiz; cihaz bir süre bekletiliyor.
settlement_in_progressCihazda gün sonu işlemi sürüyor.

details.retryAfterSeconds kadar bekleyip yeniden deneyin. Ödeme kaydı açılmadığı için aynı Idempotency-Key ile yeniden deneyebilirsiniz.

Cihazın ödemeye hazır olması

Ödeme ve ters işlem komutu yalnız ödemeye hazır bir cihaza gönderilir; komut kuyruğa alınmaz. Lunixi her istekte cihazın bağlı olduğunu, cihazdan zamanında sinyal geldiğini, cihazdaki Lunixi uygulamasının sağlıklı ve ödeme uygulamasının ulaşılabilir olduğunu ayrı ayrı denetler. Bağlantının açık olması tek başına yetmez.

HataAnlamıNe yapmalı
409 physical_pos.payment.device_offlineCihaz bağlı değil, bir süredir sinyal göndermiyor ya da cihazdaki uygulamalardan biri hazır değil.Mağazada cihazın açık ve ağa bağlı olduğunu, Lunixi uygulamasının çalıştığını kontrol edin; cihaz hazır olduğunda isteği yeniden gönderin. Kayıt açılmadığı için aynı Idempotency-Key'i kullanabilirsiniz.
503 physical_pos.presence.unavailableLunixi cihazın durumunu o an doğrulayamıyor; sebep cihazınızda değildir.Aynı Idempotency-Key ile, geri çekilerek ve sınırlı sayıda yeniden deneyin; sürerse destekle iletişime geçin.

İki hata da details.retryable: true taşır; sebebi yanıtta yer almaz. Cihazın durumunu cihaz listesinde ve cihaz ayrıntısında (GET /devices/{deviceId}) görürsünüz: presence.decision ödeme başlatıldığında alınacak sonucu (READY, NOT_READY_DEVICE → 409 device_offline, UNVERIFIABLE → 503 presence.unavailable), presence.notReadyReason cihazın neden hazır olmadığını söyler. → Cihazlar › Bağlantı durumu · Ödeme Başlatma › Cihazı seçin

Ödeme başlatmadan önce cihazı okumanız gerekmez; hazır olma durumu her istekte yeniden denetlenir. Cihazda yürüyen başka bir ödeme varsa ayrı hata döner: Cihaz başına tek aktif ödeme.

Başlatma kuralları

Ödemeyi ve ters işlemi güvenle başlatmanın kuralları Ödeme Başlatma sayfasındadır:

KuralÖzet
Idempotency-KeyBaşlatma ve ters işlemde zorunlu. Her ödeme için yeni bir UUID; ağ hatasında aynı anahtar ve aynı gövdeyle tekrar.
Aynı referansla yeni satışAynı merchantReference'lı, sonucu kesinleşmemiş ya da kısa süre önce onaylanmış satış varken yeni satış 409 alır.
Kart verisi gönderilmezKart cihazda okunur; kart verisine benzeyen alan 400 physical_pos.payment.card_data_rejected alır.
Yeniden denemeHangi hatada, ne kadar bekleyip aynı anahtarla yeniden denenir.
Oran sınırıÖdeme yazmaları: organizasyon ve API anahtarı başına 60 saniyede en çok 120 istek.

Süreler

SüreDeğer
Başlatma süresi (expiresAt)startTimeoutSeconds: 5–30 saniye, varsayılan 30. Cihaz modelinin sınırı daha kısaysa o uygulanır. Ödeme bu sürede cihazda başlamazsa EXPIRED olur.
Sonuç bekleme sınırı (resultDeadlineAt)expiresAt'tan sonra en çok 180 saniye; cihaz modeline göre daha kısa olabilir. Kesin an ödemenin resultDeadlineAt alanındadır. Sonuç gelmezse ödeme UNKNOWN olur.
Belirsiz sonuç bekletmesiVarsayılan 10 dakika; cihaz bu sürede yeni ödeme almaz. Sonra ödeme MANUAL_REVIEW olur.
İncelemedeki ödemenin arka plan sorgusu7 güne kadar.
Idempotency-Key saklama süresiEn az 7 gün.
Referans tekrarı denetimiSonucu kesinleşmemiş satış: 30 gün; onaylanmış satış: varsayılan 10 dakika.
Liste zaman penceresiVarsayılan son 31 gün, en çok 93 gün.
Webhook teslimiİstek başına 10 saniye; 12 deneme, yaklaşık 52 saat. → Webhook'lar

Tutarlar

  • API istek, yanıt ve webhook'larındaki bütün para alanları, para biriminin en küçük birimini taşıyan kanonik onluk tam sayı dizeleridir: "4500" = 45,00 TRY. Kalem fiyatları, vergiler, ters işlem tutarları, rapor toplamları ve gün sonu farkları da bu kurala dahildir.
  • Pozitif ödeme tutarları "1" veya "4500" gibi dizelerdir; negatif olmayan toplamlar "0", işaretli net/fark alanları "-4500" olabilir. JSON sayıları, ondalık metin, boşluk, baştaki artı, baştaki sıfırlar ve üs gösterimi reddedilir.
  • Ondalık girişi gerçek para birimi basamağıyla çevirin: JPY "45" → "45", TRY "45,00" → "4500", KWD "45,000" → "45000". Bu dönüşüm örnekleri her cihazın veya bankanın bu dövizleri desteklediği anlamına gelmez; yetenek ve tutar sınırları ayrıca uygulanır.
  • Taşımada tutarı dize tutun, aritmetikte kesin tam sayı/ondalık türü kullanın. Number veya parseFloat üzerinden geçirmeyin. Adetler, quantityMilli, rateBp ve rowVersion JSON tam sayı olarak kalır.
  • İsteğin gönderilen gövdesini imzalayın; webhook imzasını ayrıştırma veya alan dönüştürmeden önce özgün ham baytlar üzerinde doğrulayın. Ayrıntılar: para sözleşmesi ve 1.0 geçişi.

Sıradaki adım