Fiziksel POS
Ödeme İşlemleri
Ödeme Nesnesi

Ödeme Nesnesi

Fatura no, alıcı ve mali belge alanları ile yayın bekleyen satış uygulaması kaydının kapsamı: Satış verisi ve destek durumu. merchantReference, fatura numarası/doğrulaması yerine geçmez.

Bütün ödeme uçları ödemeyi aynı nesneyle döndürür. Bu sayfa nesnenin alanlarını, ödemenin hangi cihazda yürüyeceğini (target) ve hangi bankadan geçeceğini (terminalAcquirerId) anlatır.

Ödeme nesnesi

Bütün uçlar ödemeyi aynı nesneyle döndürür. Ters işlemler (void, iade, ön provizyon kapama ve iptali) asıl ödemeye bağlı ayrı ödeme kayıtlarıdır (çocuk ödeme); asıl ödemeye kök denir.

AlanTipAçıklama
paymentIdstring (UUID)Ödemenin kimliği. Zamana göre sıralanabilir (UUIDv7).
rootPaymentIdstring (UUID)Kökün kimliği. Kökte kendi kimliğidir.
originalPaymentIdstring | nullÇocuk ödemede asıl ödemenin kimliği; kökte null.
originstringAPI: ödeme API ya da panelden başlatıldı. DEVICE_DIRECT: satış doğrudan cihazda yapıldı.
operationstringKök: SALE, PREAUTH_OPEN, REFUND_UNMATCHED. Çocuk: VOID, REFUND, PREAUTH_CLOSE, PREAUTH_CANCEL.
paymentStatusstringÖdemenin durumu. → Ödeme durumları
statusReasonstring | nullSon geçişin sebebi. → statusReason
outcomeConflictbooleanSonuçla çelişen bir kanıt geldiyse true. Durum değişmez; ödemeyi panelde inceleyin.
resolvablebooleanMANUAL_REVIEW durumundaki ödeme panelden çözülebiliyorsa true.
deviceIdstring (UUID)İşlemi yürüten cihaz.
logicalTerminalIdstring | nullİşlemin yürüdüğü mantıksal terminal.
terminalAcquirerIdstring | nullİşlemin banka satırı. null: bankayı cihaz seçti. → Banka satırı
channelstringCihazla haberleşme kanalı: APP2APP, LOCAL_REST ya da VENDOR_CLOUD.
vendorReferencestring | nullÖdemenin cihaz tarafındaki referansı: paymentId'nin tiresiz yazımı. Cihaz fişinde ve üretici kayıtlarında bu değeri görürsünüz.
amountMinorstringİstenen tutar, en küçük birimde.
approvedAmountMinorstring | nullOnaylanan tutar. Sonuç gelmeden null; kısmi onayda amountMinor'dan küçük.
currencystringISO 4217 para birimi.
installmentCountinteger | nullTaksit sayısı; peşin ödemede null.
instrumentstringÖdeme aracı. API ya da panelden başlatılan ödemede CARD ya da MEAL_CARD (yemek kartı). Doğrudan cihazda yapılan satışta (origin: "DEVICE_DIRECT") CARD, MEAL_CARD, QR, WALLET, CASH, BANK_TRANSFER, OTHER değerlerinden biri; değer kümesi büyüyebilir; kodunuz tanımadığı bir değerde hata vermemelidir.
merchantReferencestring | nullKendi referansınız.
cashierobject | nullÖdeme cihazda bir kasiyer oturumunda başlatıldıysa kasiyer: { "cashierId": "…", "cashierCode": "…", "displayName": "…" }. displayName kasiyerin güncel adıdır. Kasiyerler panelden yönetilir. Kasiyer yoksa null.
reversedMinorstringKökte: onaylanan iadeler, void ve ön provizyon iptalinin toplamı.
capturedMinorstringKökte: ön provizyon kapamayla tahsil edilen tutar.
reversalReservedMinorstringKökte: sonuçlanmamış ters işlemin ayırdığı tutar.
pendingReversalIdstring | nullKökte: sonuçlanmamış ters işlemin paymentId değeri.
reversalStatusstringKökte ters işlemlerin toplam etkisi. → reversalStatus
expiresAtstring | nullÖdemenin cihazda başlaması için son an.
resultDeadlineAtstring | nullSonucun beklendiği son an; sonrasında ödeme UNKNOWN olur.
completedAtstring | nullSon duruma geçiş anı.
settledAtstring | nullÖdemenin girdiği gün sonunun anı; gün sonuna girmediyse null. Kökte doluysa void yapılamaz, iade yapılır. → Gün sonu ve void
settlementBatchNostring | nullÖdemenin girdiği gün sonunun numarası; yoksa null.
createdAtstringOluşturulma zamanı.
updatedAtstring | nullSon değişiklik zamanı.
rowVersionintegerKaydın sürümü; her durum değişikliğinde artar.
historySeqintegerDurum geçmişinin sıra numarası. Webhook'ların sırasını bununla doğrularsınız. → Sıra ve tekrar
tenderobject | nullKart sonucu; aşağıya bakın.
itemsarraySatış kalemleri. Yalnız GET /payments/{paymentId} ve işlem ayrıntısı yanıtlarında ve kalemli satışta dolu; diğer yanıtlarda boş dizi. → Kalemler
refundItemsarrayKalem bazlı iadenin satırları. Yalnız GET /payments/{paymentId} ve işlem ayrıntısı yanıtlarında ve kalemli iadede dolu. → Kalemler

tender nesnesi:

AlanTipAçıklama
tenderStatusstringPENDING, APPROVED, PARTIALLY_APPROVED, DECLINED, CANCELLED ya da UNKNOWN.
cardMaskedstring | nullMaskeli kart numarası: ilk 6 ve son 4 hane (454360******1234) ya da yalnız son 4 hane.
cardBrandstring | nullVISA, MASTERCARD, TROY, AMEX, UNIONPAY ya da OTHER.
entryModestring | nullKartın okunma biçimi: CHIP, CONTACTLESS, SWIPE, MANUAL, QR ya da OTHER.
acquirerCodestring | nullİşlemi yapan bankanın dört haneli kodu. → Katalog › Bankalar
authCodestring | nullBankanın onay kodu.
rrnstring | nullBankanın işlem referans numarası (RRN).

Kart numarasının tamamı, son kullanma tarihi ve güvenlik kodu hiçbir yanıtta yer almaz.

Hedef cihaz

Ödeme her zaman bir cihazda yürür. target nesnesinde cihazı aşağıdaki biçimlerden tam olarak biriyle belirtirsiniz:

BiçimAçıklama
{ "deviceId": "…" }Cihazın kimliği. → Cihazlar
{ "vendorCode": "…", "serialNumber": "…" }Üretici kodu ve seri numarası. Üretici kodu zorunludur (PAVO, CASTLES ya da PLUSPAY); seri, cihaz kaydındaki kurala göre karşılaştırılır. → Seri numarası biçimi
{ "externalRef": "…" }Cihazı kaydederken verdiğiniz externalRef.
  • Hedef yoksa, birden çok hedef verildiyse ya da biçim hatalıysa istek 400 physical_pos.payment.target_invalid alır; details.reason: none, multiple, vendor_code_required, device_id_invalid, external_ref_invalid ya da invalid (target nesne değil).
  • Bilinmeyen üretici kodu 400 physical_pos.device.vendor_unknown alır.
  • target alanlarından biri dize değilse ya da uzunluk sınırını aşıyorsa (deviceId 64, vendorCode 32, serialNumber ve externalRef 128 karakter) istek alanın tipli kodunu alır: deviceId için physical_pos.payment.target_invalid (device_id_invalid), externalRef için physical_pos.payment.target_invalid (external_ref_invalid), vendorCode için physical_pos.device.vendor_unknown (invalid), serialNumber için physical_pos.input.serial_invalid (dize değilse invalid, uzunsa too_long). details.field alanın noktalı yolunu verir (target.serialNumber gibi). target içinde tanımlanmamış bir alan 400 VALIDATION_ERROR alır.
  • Bulunamayan cihaz, başka organizasyonun ya da diğer ortamın cihazı ve emekli cihaz aynı cevabı alır: 404 physical_pos.device.not_found.
  • Ödeme, cihazın bağlı olduğu mantıksal terminalde yürür. Cihaz bir terminale bağlı değilse 409 physical_pos.payment.terminal_not_payable (details.reason: not_linked). → Cihaz Bağı
  • Mağaza, kasa ya da terminal kimliğiyle hedefleme yoktur.

Ödeme alabilmek için:

  • cihaz lifecycleStatus: "ACTIVE" ve ownershipStatus: "VERIFIED" olmalı; aksi 409 physical_pos.payment.device_not_payable (details.reason: ownership_unverified, lifecycle_<durum> ya da pairing_hold ve details.retryAfterSeconds);
  • cihazın haberleşme kanalı tanımlı olmalı; integrationChannel: "UNSET" cihaz 422 physical_pos.payment.operation_unsupported (details.reason: channel_unset) alır;
  • terminal açık ve etkin olmalı; aksi 409 physical_pos.payment.terminal_not_payable (details.reason: status_<durum> ya da ownership_unverified);
  • cihaz ödemeye hazır olmalı: bağlı olmalı ve cihazdaki Lunixi uygulaması ile ödeme uygulaması çalışır durumda olmalı. Aksi 409 physical_pos.payment.device_offline (details.retryable: true); Lunixi cihazın durumunu o an doğrulayamıyorsa 503 physical_pos.presence.unavailable. Ödeme kuyruğa alınmaz; cihaz hazır olduğunda yeniden başlatın. Cihazın neden hazır olmadığını cihaz ayrıntısındaki presence.notReadyReason alanında görürsünüz. → Cihazın ödemeye hazır olması

Banka satırı

Ödemenin hangi bankadan geçeceğini iki yolla belirlersiniz:

  • terminalAcquirerId gönderirsiniz: terminalin banka satırlarından birinin id değeri. Satır acquirerStatus: "ACTIVE", mappingStatus: "MAPPED" olmalı ve ödemenin para birimini currencies listesinde taşımalıdır. Uygun değilse 422 physical_pos.payment.operation_unsupported (details.reason: terminal_acquirer_not_eligible).
  • Göndermezsiniz: bankayı cihaz ya da cihazdaki ödeme uygulaması seçer; terminalde tek banka satırı olsa bile Lunixi seçim yapmaz. Ödemede terminalAcquirerId null olur.

Ters işlemler terminalAcquirerId almaz; banka ters işlem kurallarıyla belirlenir.

Uygulama kimliği

SoftPOS cihazlarda ve uygulamayla bağlanan cihazlarda (APP2APP, LOCAL_REST kanalları) ödeme ve ters işlem için panelde Uygulama Görünümü ayarlarında kimlik doğrulama açık olmalı ve cihazın ortamına uygun, etkin bir yayınlanabilir anahtar seçili olmalıdır. Değilse istek 422 physical_pos.payment.identity_required alır:

details.reasonAnlamı
disabledKimlik doğrulama kapalı.
key_missingSeçili anahtar yok ya da cihazın ortamına uymuyor.
key_not_owned, key_inactive, key_product_missingSeçili anahtar size ait değil, etkin değil ya da Fiziksel POS ürünü tanımlı değil.
key_changedİstek sırasında seçili anahtar değişti; yeniden deneyin.

Başlamadan iptal bu denetime girmez. Anahtar durumu okunamazsa 503 physical_pos.dependency.unavailable döner.