Bağlantı Yöntemleri
Ödemeyi hangi cihazda başlatırsanız başlatın, aynı isteği gönderirsiniz: POST /api/v1/physical-pos/payments. İsteğin cihaza hangi yoldan gideceğini Lunixi, cihaz kaydındaki bağlantı yöntemine (integrationChannel) göre seçer. Kodunuzda bağlantı yöntemine göre bir ayrım yapmanız gerekmez; istek, yanıt, webhook'lar ve hata kodları her yöntemde aynıdır.
Bağlantı yöntemleri
integrationChannel | Cihazda ne olmalı | Lunixi isteği nasıl iletir | Ne zaman uygundur |
|---|---|---|---|
APP2APP | Lunixi uygulaması kurulu ve çalışır durumda. | Uygulamanın Lunixi ile kurduğu güvenli, sürekli açık bağlantı üzerinden imzalı komut gönderir. Uygulama komutu doğrular ve cihazdaki ödeme uygulamasını başlatır. | Cihaza Lunixi uygulamasını kurabildiğiniz ve ödeme uygulamasının başka bir uygulama tarafından başlatılabildiği modellerde. |
LOCAL_REST | Lunixi uygulaması kurulu ve çalışır durumda. | Komut aynı güvenli, sürekli açık bağlantıyla uygulamaya ulaşır. Uygulama ödemeyi cihazın kendi yerel arayüzü üzerinden başlatır. | Ödeme uygulamasının cihaz içinde yerel bir arayüz sunduğu modellerde. |
VENDOR_CLOUD | Lunixi uygulaması gerekmez. Cihaz açık ve internete bağlı olmalı, panelde Entegrasyonlar bölümünde tanımladığınız üretici hesabına bağlı olmalıdır (cihaz ayrıntısında vendorAccount dolu). | İsteği, üretici hesabınızın bilgileriyle cihaz üreticisinin bulut servisine iletir; bulut servisi ödemeyi cihazda başlatır. | Cihaza uygulama kurmadan, cihazı üreticinin bulut servisi üzerinden kullandığınız durumlarda. |
UNSET bağlantı yöntemi tanımlanmamış demektir; bu cihaza ödeme başlatılamaz (422 physical_pos.payment.operation_unsupported, channel_unset). appMode (CASHIER, KIOSK gibi) yalnız Lunixi uygulamasıyla çalışan APP2APP ve LOCAL_REST yöntemlerinde kullanılır.
Bağlantı yöntemini görme ve değiştirme
- Belirleme: Cihazı kaydederken
integrationChannelalanıyla siz belirlersiniz (panelden ya daPOST /api/v1/physical-pos/devices). → Cihazlar › Cihaz kaydetme - Görme: Panelde cihaz ayrıntısında; API'de cihaz listesi ve
GET /api/v1/physical-pos/devices/{deviceId}yanıtındakiintegrationChannelalanında. Bir ödemenin hangi yöntemle yürüdüğü ödeme nesnesininchannelalanındadır. - Değiştirme: Panelde cihaz düzenleme penceresinden ya da
PATCH /api/v1/physical-pos/devices/{deviceId}ile (integrationChannel,physical_pos:managekapsamı). → Cihazlar › Cihaz güncelleme
Lunixi isteği kayıttaki yönteme göre gönderir. Kayıttaki yöntem, cihazın gerçekte çalıştığı yöntemle aynı olmalıdır; yöntemi değiştirdiğinizde cihazdaki ayarın da buna uyduğundan emin olun.
Cihaz modeline göre yöntem ve işlemler
- Bazı cihaz modelleri aynı anda yalnız bir bağlantı yöntemiyle çalışır; yöntem cihazın kendi ayarıyla değişir. Bazı modeller birden çok yöntemi birlikte destekler.
- Hangi yöntemin ve hangi işlemlerin (satış, ön provizyon, iade gibi) desteklendiği cihaz modeline bağlıdır. Cihaz ayrıntısındaki
capabilitiesözeti, cihazın kayıtlı yöntemi için tanımlı işlemleri (operations) ve iade desteğini gösterir. Tanım yoksacapabilities.stateUNDEFINEDolur ve ödeme422 physical_pos.payment.operation_unsupported(capability_undefined) alır. - Birden çok yöntemi destekleyen bazı modellerde, belirli bir işlem modelin tanımına göre sabit olarak diğer yoldan gönderilebilir. Bu seçim önceden belirlidir; bir hatadan sonra değişmez.
Uygulama kapalıysa ya da cihaz çevrimdışıysa
- Lunixi komutu göndermeden önce, her istekte cihazın ödemeye hazır olduğunu denetler. → Adım 1
- Cihaz hazır değilse istek
409 physical_pos.payment.device_offlineya da503 physical_pos.presence.unavailablealır. Ödeme kaydı açılmaz ve komut kuyruğa alınmaz. - Lunixi isteği kendiliğinden başka bir yoldan (ör. üreticinin bulut servisinden) yeniden göndermez. Bu, aynı ödemenin iki farklı yoldan iki kez çekilmesini önler.
- Siz cihazın durumunu (
presence.decision,presence.notReadyReason) kontrol edin; cihaz hazır olduğunda isteği aynıIdempotency-Keyve aynı gövdeyle yeniden gönderin. → Yeniden deneme
Komut cihaza gönderildikten sonra bağlantı koparsa ödeme yeniden gönderilmez; sonuç süresi içinde gelmezse ödeme UNKNOWN olur. → Sonuç belirsiz olursa
Cihazdan başlayan satışlar
Kasiyer satışı doğrudan cihazda başlatırsa sizin tarafınızdan API isteği yapılmaz. Satış origin: "DEVICE_DIRECT" ile kaydedilir; size physical_pos.payment.device_sale webhook'uyla bildirilir ve işlem listesinde görünür. → Ödeme Akışı › Cihazda doğrudan satış
SoftPOS ve doğrudan bağlantı
- Katalogda ve cihaz kayıtlarında
deviceType: "SOFTPOS"(kart kabul eden telefon ya da tablet) değeri bulunur. SoftPOS ile kart kabulü için kullanıma açık bir akış henüz yoktur. - Kasa yazılımınızın cihazla yerel ağ ya da kablo (seri, USB) üzerinden doğrudan konuşması Lunixi API'si üzerinden yapılmaz. Bu sayfadaki akış, ödeme isteğini Lunixi'ye gönderdiğiniz entegrasyondur.
Cihaz kabul etti ama ödeme hiç başlamadıysa
Uygulama komutu kaydetmiş, ancak ödeme uygulamasını hiç çağırmamış olabilir: örneğin süre dolmuş veya hazırlık tamamlanamamıştır. Destekleyen uygulama sürümü komutun daha sonra da çalışamayacağını kalıcı kayda alır; Lunixi bu kaydı doğruladığında işlem EXPIRED, gerekçesi DEVICE_EXECUTION_INHIBITED olur. Normal ödeme sorgusu ve webhook sonucu izlenir. Banka reddi ya da karttan çekim sonucu üretilmez.
Bu kapanış, ödeme uygulamasına gönderilmiş bir işlemin zaman aşımına uygulanmaz. Böyle bir işlem belirsiz kalırsa sorgulanır; yeni tahsilat veya başka bağlantı yöntemine otomatik geçiş yapılmaz. Eski uygulamada kesin başlamama kanıtı yoksa mevcut sorgu/inceleme yolu sürer. Bu özellik uygulama ve sunucunun uyumlu sürümlerinin yayına alınmasını gerektirir; dokümandaki kaynak teslimi canlı sürüm doğrulaması değildir.
Pavo APP2APP kaynak durumu — 8 Kasım 2026
Satış/iade/iptal sürücüsü ve salt okunur kurtarma Android kaynakta bağlıdır. PavoPay'in kurulu olması, dönüşün güvenilirliğinin veya sandbox modunun doğrulandığı anlamına gelmez. Açılış ve finansal sonuç doğrulaması ayrı kontrollerdir; kabul edilmiş üretici build/dönüş/mod profili olmadan uygulama ödemeye hazır bildirmez. Güncel destek sınırları. Intent hatasında LOCAL_REST veya VENDOR_CLOUD'a kendiliğinden geçilmez.