Ö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.
| Alan | Tip | Açıklama |
|---|---|---|
paymentId | string (UUID) | Ödemenin kimliği. Zamana göre sıralanabilir (UUIDv7). |
rootPaymentId | string (UUID) | Kökün kimliği. Kökte kendi kimliğidir. |
originalPaymentId | string | null | Çocuk ödemede asıl ödemenin kimliği; kökte null. |
origin | string | API: ödeme API ya da panelden başlatıldı. DEVICE_DIRECT: satış doğrudan cihazda yapıldı. |
operation | string | Kök: SALE, PREAUTH_OPEN, REFUND_UNMATCHED. Çocuk: VOID, REFUND, PREAUTH_CLOSE, PREAUTH_CANCEL. |
paymentStatus | string | Ödemenin durumu. → Ödeme durumları |
statusReason | string | null | Son geçişin sebebi. → statusReason |
outcomeConflict | boolean | Sonuçla çelişen bir kanıt geldiyse true. Durum değişmez; ödemeyi panelde inceleyin. |
resolvable | boolean | MANUAL_REVIEW durumundaki ödeme panelden çözülebiliyorsa true. |
deviceId | string (UUID) | İşlemi yürüten cihaz. |
logicalTerminalId | string | null | İşlemin yürüdüğü mantıksal terminal. |
terminalAcquirerId | string | null | İşlemin banka satırı. null: bankayı cihaz seçti. → Banka satırı |
channel | string | Cihazla haberleşme kanalı: APP2APP, LOCAL_REST ya da VENDOR_CLOUD. |
vendorReference | string | 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. |
amountMinor | string | İstenen tutar, en küçük birimde. |
approvedAmountMinor | string | null | Onaylanan tutar. Sonuç gelmeden null; kısmi onayda amountMinor'dan küçük. |
currency | string | ISO 4217 para birimi. |
installmentCount | integer | null | Taksit sayısı; peşin ödemede null. |
instrument | string | Ö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. |
merchantReference | string | null | Kendi referansınız. |
cashier | object | 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. |
reversedMinor | string | Kökte: onaylanan iadeler, void ve ön provizyon iptalinin toplamı. |
capturedMinor | string | Kökte: ön provizyon kapamayla tahsil edilen tutar. |
reversalReservedMinor | string | Kökte: sonuçlanmamış ters işlemin ayırdığı tutar. |
pendingReversalId | string | null | Kökte: sonuçlanmamış ters işlemin paymentId değeri. |
reversalStatus | string | Kökte ters işlemlerin toplam etkisi. → reversalStatus |
expiresAt | string | null | Ödemenin cihazda başlaması için son an. |
resultDeadlineAt | string | null | Sonucun beklendiği son an; sonrasında ödeme UNKNOWN olur. |
completedAt | string | null | Son duruma geçiş anı. |
settledAt | string | 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 |
settlementBatchNo | string | null | Ödemenin girdiği gün sonunun numarası; yoksa null. |
createdAt | string | Oluşturulma zamanı. |
updatedAt | string | null | Son değişiklik zamanı. |
rowVersion | integer | Kaydın sürümü; her durum değişikliğinde artar. |
historySeq | integer | Durum geçmişinin sıra numarası. Webhook'ların sırasını bununla doğrularsınız. → Sıra ve tekrar |
tender | object | null | Kart sonucu; aşağıya bakın. |
items | array | Satış 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 |
refundItems | array | Kalem 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:
| Alan | Tip | Açıklama |
|---|---|---|
tenderStatus | string | PENDING, APPROVED, PARTIALLY_APPROVED, DECLINED, CANCELLED ya da UNKNOWN. |
cardMasked | string | null | Maskeli kart numarası: ilk 6 ve son 4 hane (454360******1234) ya da yalnız son 4 hane. |
cardBrand | string | null | VISA, MASTERCARD, TROY, AMEX, UNIONPAY ya da OTHER. |
entryMode | string | null | Kartın okunma biçimi: CHIP, CONTACTLESS, SWIPE, MANUAL, QR ya da OTHER. |
acquirerCode | string | null | İşlemi yapan bankanın dört haneli kodu. → Katalog › Bankalar |
authCode | string | null | Bankanın onay kodu. |
rrn | string | null | Bankanı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çim | Açı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_invalidalır;details.reason:none,multiple,vendor_code_required,device_id_invalid,external_ref_invalidya dainvalid(targetnesne değil). - Bilinmeyen üretici kodu
400 physical_pos.device.vendor_unknownalır. targetalanlarından biri dize değilse ya da uzunluk sınırını aşıyorsa (deviceId64,vendorCode32,serialNumberveexternalRef128 karakter) istek alanın tipli kodunu alır:deviceIdiçinphysical_pos.payment.target_invalid(device_id_invalid),externalRefiçinphysical_pos.payment.target_invalid(external_ref_invalid),vendorCodeiçinphysical_pos.device.vendor_unknown(invalid),serialNumberiçinphysical_pos.input.serial_invalid(dize değilseinvalid, uzunsatoo_long).details.fieldalanın noktalı yolunu verir (target.serialNumbergibi).targetiçinde tanımlanmamış bir alan400 VALIDATION_ERRORalı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"veownershipStatus: "VERIFIED"olmalı; aksi409 physical_pos.payment.device_not_payable(details.reason:ownership_unverified,lifecycle_<durum>ya dapairing_holdvedetails.retryAfterSeconds); - cihazın haberleşme kanalı tanımlı olmalı;
integrationChannel: "UNSET"cihaz422 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 daownership_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ıyorsa503 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ındakipresence.notReadyReasonalanında görürsünüz. → Cihazın ödemeye hazır olması
Banka satırı
Ödemenin hangi bankadan geçeceğini iki yolla belirlersiniz:
terminalAcquirerIdgönderirsiniz: terminalin banka satırlarından birininiddeğeri. SatıracquirerStatus: "ACTIVE",mappingStatus: "MAPPED"olmalı ve ödemenin para biriminicurrencieslistesinde taşımalıdır. Uygun değilse422 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
terminalAcquirerIdnullolur.
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.reason | Anlamı |
|---|---|
disabled | Kimlik doğrulama kapalı. |
key_missing | Seçili anahtar yok ya da cihazın ortamına uymuyor. |
key_not_owned, key_inactive, key_product_missing | Seç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.