Ö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.
- Ödemeyi adım adım başlatmak için: Ödeme Başlatma
- Uçların alanları ve hata kodları: Ödeme İşlemleri
Akış
- Kabul: Başlatma isteği
202 Acceptedile kabul edilir ve ödemeNOT_STARTEDdurumunda açılır. Bu yanıt "ödeme kabul edildi" demektir, "ödendi" demek değildir. - Cihazda: Cihaz ödemeyi başlattığında ödeme
IN_PROGRESSolur: 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ı
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.
| Durum | Anlamı | Son durum mu? |
|---|---|---|
NOT_STARTED | Ödeme kaydı açıldı, cihaz ödemeyi henüz başlatmadı. | Hayır |
IN_PROGRESS | Cihaz ödemeyi başlattı; kart ya da banka cevabı bekleniyor. | Hayır |
APPROVED | Para çekildi. Ters işlemde: void, iade ya da kapama gerçekleşti. | Evet |
PARTIALLY_APPROVED | Para çekildi ama istenenden az; çekilen tutar approvedAmountMinor. | Evet |
DECLINED | Banka 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 |
UNKNOWN | Sonuç bilinmiyor; para çekilmiş olabilir. Sonuç otomatik olarak doğrulanıyor. → Sonucu belirsiz ödeme | Hayır |
MANUAL_REVIEW | Sonuç otomatik doğrulamayla netleşmedi; ödeme panelden çözülür. → Sonucu belirsiz ödeme | Hayır |
- Son duruma geçen ödemenin durumu değişmez. Sonradan farklı bir sonuç kanıtı gelirse durum korunur, ödemede
outcomeConflict: trueolur ve bu kanıt için webhook gönderilmez.outcomeConflict: truegördüğünüzde ödemeyi panelde inceleyin. - Zaman aşımı başarısızlık değildir. Sonuç
resultDeadlineAtanına kadar gelmezse ödemeDECLINEDdeğilUNKNOWNolur.
Ters işlem durumu: reversalStatus
Asıl ödemede (kökte) ters işlemlerin toplam etkisini gösterir:
| Değer | Anlamı |
|---|---|
NONE | Ters işlem yok. |
PARTIALLY_REFUNDED | Kısmi iade yapıldı; yeni iade yapılabilir. |
REFUNDED | Tamamı iade edildi. |
VOIDED | Void 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ğer | Anlamı |
|---|---|
MERCHANT_CANCELLED_BEFORE_DISPATCH | Ödemeyi komut cihaza ulaşmadan iptal ettiniz (EXPIRED). |
COMMAND_EXPIRED_BEFORE_DISPATCH | Baş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_UNKNOWN | Komutun cihaza ulaşıp ulaşmadığı doğrulanamadı (UNKNOWN). Ödemeyi yeniden başlatmayın. |
RESULT_DEADLINE_PASSED | Sonuç süresi içinde gelmedi (UNKNOWN). Ödemeyi yeniden başlatmayın. |
UNKNOWN_HOLD_EXPIRED | Sonuç 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_EXPIRED | Yemek kartı kodunun süresi doldu, ödeme yapılmadı (EXPIRED). |
PROVIDER_CODE_WINDOW_ELAPSED | Yemek 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_REJECTED | Cihaz ü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.
- Ödeme
UNKNOWNolduğundaphysical_pos.payment.unknownwebhook'u gönderilir. Bu olayın anlamı "tekrar tahsil etmeyin, sonuç doğrulanıyor"dur. - 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. - Sonuç bu sürede kesinleşirse ödeme son durumuna geçer ve ilgili webhook gönderilir.
- Sonuç netleşmezse ödeme
MANUAL_REVIEWolur,physical_pos.payment.manual_reviewwebhook'u gönderilir ve cihaz yeniden ödeme alabilir. Sonuç arka planda 7 güne kadar sorgulanmaya devam eder. MANUAL_REVIEWdurumundaki ö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. Ödemederesolvable: trueise ödeme panelden çözülebilir. Bu işlemin API ucu yoktur.- 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.
- Satış kaydedildiğinde
physical_pos.payment.device_salewebhook'u gönderilir. → Webhook Olayları › Cihazda doğrudan satış - Satışı ödeme ve işlem uçlarından da okursunuz. → İşlemler
- Satışı yalnız iade edebilirsiniz; void yapılamaz. İade yalnız satışın yapıldığı cihazda yürür. → Ödemeler › Cihazda doğrudan satışın iadesi
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.reason | Anlamı |
|---|---|
payment_in_progress | Cihazda yürüyen bir ödeme var. |
unknown_outcome_hold | Cihazdaki bir ödemenin sonucu belirsiz; cihaz bir süre bekletiliyor. |
settlement_in_progress | Cihazda 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.
| Hata | Anlamı | Ne yapmalı |
|---|---|---|
409 physical_pos.payment.device_offline | Cihaz 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.unavailable | Lunixi 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-Key | Baş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önderilmez | Kart cihazda okunur; kart verisine benzeyen alan 400 physical_pos.payment.card_data_rejected alır. |
| Yeniden deneme | Hangi 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üre | Değ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ç bekletmesi | Varsayılan 10 dakika; cihaz bu sürede yeni ödeme almaz. Sonra ödeme MANUAL_REVIEW olur. |
| İncelemedeki ödemenin arka plan sorgusu | 7 güne kadar. |
Idempotency-Key saklama süresi | En az 7 gün. |
| Referans tekrarı denetimi | Sonucu kesinleşmemiş satış: 30 gün; onaylanmış satış: varsayılan 10 dakika. |
| Liste zaman penceresi | Varsayı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.
NumberveyaparseFloatüzerinden geçirmeyin. Adetler,quantityMilli,rateBpverowVersionJSON 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
- Ödemeyi adım adım başlatmak: Ödeme Başlatma
- Uçlar, alanlar ve örnekler: Ödeme İşlemleri
- Kalemli satış ve kalem bazlı iade: Satış Kalemleri · Kalem Bazlı İade
- Sonuç bildirimleri: Webhook Olayları