Hızlı Başlangıç: İlk Ödeme
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.
- Taban yol
/api/v1/physical-pos- Kimlik
- Her istekte Ed25519 istek imzası —
X-Key-Id,X-Date,X-Nonce,X-Signature; gövdeli isteklerde ayrıcaDigest. Zaman penceresi ±5 dk, nonce tek kullanımlık. Bearer jetonu ya da panel oturumu bu uçlarda kabul edilmez. - Yetki
- Anahtarınız Fiziksel POS ürününü (
PHYSICAL_POS) ve bu sayfadaki uçların kapsamını taşımalıdır:physical_pos:payments·physical_pos:view. Ürünü olmayan anahtar403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar403 API_INSUFFICIENT_SCOPEalır. Bkz. Kimlik Doğrulama ve Kapsamlar. - Çapraz yüzey
- Bu uçlar s2s yüzeyindedir; kendi sunucunuzdan imzalı istekle çağırırsınız. Aynı kayıtların panelde ekranları var, ama panel uçları API anahtarıyla çağrılamaz; bu uçlar da panel oturumuyla çağrılamaz.
Bu rehber, kendi sunucunuzdan mağazanızdaki bir POS cihazında satışı baştan sona başlatmayı anlatır: cihazı seçersiniz, ödemeyi başlatırsınız, yanıtı okursunuz ve sonucu alırsınız. Kart cihazda okunur; API kart verisi almaz.
Ö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.
1. Cihazı seçin GET /devices → presence.decision: READY
2. Ödemeyi başlatın POST /payments → 202 · paymentStatus: NOT_STARTED
3. Yanıtı saklayın paymentId, resultDeadlineAt
4. Sonucu alın webhook physical_pos.payment.* ya da GET /payments/{paymentId}Ödemenin durum makinesi, ters işlemler ve gün sonu: Ödeme Akışı. Uçların bütün alanları ve hata kodları: Ödeme İşlemleri.
Başlamadan önce
API anahtarı ve kapsamlar
| Gereksinim | Açıklama |
|---|---|
Canlı API anahtarı (mk_live_…) | Ödemeyi canlı anahtarla başlatırsınız. Test anahtarı ödemeleri yalnız okur; başlatma isteği 403 physical_pos.environment.test_key_read_only alır. → Ortamlar |
| Fiziksel POS ürünü | Anahtarınızda PHYSICAL_POS ürünü tanımlı olmalıdır; değilse 403 PRODUCT_NOT_ENABLED. |
physical_pos:payments kapsamı | Ödeme başlatma, ters işlem ve iptal yalnız bu kapsamla yapılır. Bu kapsam ödemeleri, işlemleri ve raporları da okur. |
physical_pos:view kapsamı | Cihazları okumak için gerekir (Adım 1). physical_pos:manage ödeme yapamaz ve okuma yetkisi içermez. |
| İstek imzası | Her istek API anahtarınızla imzalanır; gövdeli isteklerde Digest başlığı da gönderilir. → Kimlik Doğrulama › İmza yardımcısı |
Mevcut anahtarlarınıza physical_pos:payments kendiliğinden eklenmez; panelde anahtarın yetki ayarlarından seçin. → Kapsamlar
Test ortamında ödeme başlatılamaz. Okuma isteklerini, imzayı ve kapsam hatalarını test anahtarıyla deneyebilirsiniz; ödemeyi canlı anahtarla ve gerçek bir cihazla başlatırsınız. Canlı anahtarı yalnız sunucunuzda saklayın.
Cihaz ve terminal
Cihazın ödeme alabilmesi için aktif ve size ait olduğu doğrulanmış olması, bir mantıksal terminale bağlı olması ve Lunixi'ye bağlı olarak hazır beklemesi gerekir. Cihazı sıfırdan hazırlama adımları ve koşulların tam listesi: Cihazı Ödemeye Hazırlama.
Ödeme isteği cihaza nasıl ulaşır?
Ödeme isteği, cihaz kaydındaki bağlantı yöntemine (integrationChannel) göre cihazdaki Lunixi uygulamasına ya da üreticinin bulut servisine iletilir; siz her durumda aynı isteği gönderirsiniz. Yöntemler, cihaz modeline göre farklar ve cihaz çevrimdışıyken ne olduğu: Bağlantı Yöntemleri.
Adım 1 — Cihazı seçin
Ödemeyi başlatacağınız cihazı listeden seçin. Liste satırları cihazın bağlantı durumunun özetini (presence) taşır; hangi cihazın ödemeye hazır olduğunu tek istekte görürsünüz.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices?storeId=00000000-0000-0000-0000-000000000101&lifecycleStatus=ACTIVE&ownershipStatus=VERIFIED"
lunixi_sign GET "$REQ_PATH"
curl "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"Yanıttaki her satırda şu alanlara bakın (satırın diğer alanları: Cihazlar › Cihaz nesnesi):
{
"id": "00000000-0000-0000-0000-000000000401",
"displayName": "Kasa 1 POS",
"lifecycleStatus": "ACTIVE",
"ownershipStatus": "VERIFIED",
"integrationChannel": "APP2APP",
"logicalTerminal": { "id": "00000000-0000-0000-0000-000000000301", "code": "IST-KADIKOY-01" },
"presence": {
"connectionState": "ONLINE",
"lastSeenAt": "2026-01-02T08:59:50.000Z",
"readyForPayment": true,
"notReadyReason": null,
"decision": "READY",
"source": "LIVE"
}
}presence.decision, ödeme başlatıldığında cihazın hazır olma denetiminin vereceği sonuçtur:
presence.decision | Anlamı | Ödeme başlatırsanız |
|---|---|---|
READY | Cihaz bağlı ve ödeme almaya hazır. | Hazır olma denetiminden geçer. |
NOT_READY_DEVICE | Cihaz bağlı değil, bir süredir sinyal göndermiyor ya da cihazdaki uygulamalardan biri hazır değil. Sebep presence.notReadyReason alanındadır. | 409 physical_pos.payment.device_offline |
UNVERIFIABLE | Lunixi cihazın durumunu o an doğrulayamıyor; sebep cihazınızda değildir. | 503 physical_pos.presence.unavailable |
- Değer kümesi büyüyebilir; tanımadığınız değeri
READYsaymayın.presenceokunamadıysanulldöner. presenceyalnız bağlantıyı ve cihazdaki uygulamaları değerlendirir. Cihazın durumu, sahipliği ve terminal bağı yukarıdaki koşullara göre ayrıca denetlenir.- Cihazın neden hazır olmadığını ve cihazda yürüyen bir ödeme olup olmadığını (
presence.busy) cihaz ayrıntısında görürsünüz:GET /api/v1/physical-pos/devices/{deviceId}. → Cihazlar › Bağlantı durumu - Bu okuma isteğe bağlıdır. Hazır olma durumu her ödeme isteğinde yeniden denetlenir; cihaz okuma ile ödeme arasında bağlantısını kaybedebilir.
Cihazın id değerini ödemede target.deviceId olarak kullanırsınız. Kendi sisteminizdeki cihaz kimliğiyle çalışıyorsanız cihazı kaydederken verdiğiniz externalRef ile de hedefleyebilirsiniz: Hedef cihaz.
Adım 2 — Ödemeyi başlatın
Idempotency-Key üretin ve saklayın
Ödeme başlatma ve ters işlem isteklerinde Idempotency-Key başlığı zorunludur. Anahtar, ağ hatasından sonra aynı satış için ikinci bir ödeme açılmasını önler.
- Her ödeme için yeni bir UUID üretin.
- Anahtarı isteği göndermeden önce, siparişinizle birlikte kendi kaydınıza yazın.
- İsteği bu anahtarla gönderin. Aynı ödemenin bütün denemelerinde aynı anahtarı ve aynı gövdeyi kullanın.
| Uç | Idempotency-Key |
|---|---|
POST /payments | Zorunlu |
POST /payments/{paymentId}/reversals | Zorunlu |
POST /payments/{paymentId}/cancel | İsteğe bağlı |
Biçim: 8–200 karakter, boşluksuz yazdırılabilir ASCII. Başlık yoksa 400 physical_pos.idempotency.key_required, biçim dışıysa 400 physical_pos.idempotency.key_invalid.
| Durum | Sonuç |
|---|---|
| Yeni anahtar | Ödeme açılır: 202, replayed: false. |
| Aynı anahtar, aynı gövde | Yeni ödeme açılmaz; ödemenin güncel hâli döner: 200, replayed: true. Yanıt ilk yanıtın kopyası değildir, ödemenin o anki durumunu verir. |
| Aynı anahtar, farklı gövde ya da farklı işlem (ör. satışın anahtarıyla iade) | 409 physical_pos.idempotency_mismatch. |
- Gövdeler alan kuralları uygulandıktan sonraki hâlleriyle karşılaştırılır; alanların sırası fark etmez.
- Ters işlemde yoldaki
paymentIdde karşılaştırmaya girer. - İstek alan kuralına, cihaz ya da terminal denetimine takılıp reddedildiyse (ör.
400,404,409 device_busy,409 device_offline,422) hiçbir kayıt yazılmaz; aynı anahtarla yeniden deneyebilirsiniz. - Anahtar en az 7 gün saklanır. Bu sürenin sonunda aynı anahtar yeni bir ödeme açar: her ödeme için yeni bir UUID kullanın; anahtarı yeniden kullanmayın.
- Panel ve canlı API anahtarınız aynı anahtar alanını paylaşır.
Ağ hatasında aynı anahtarla yeniden deneyin. Zaman aşımı, bağlantı kopması, 5xx ya da 503 physical_pos.service.busy aldığınızda isteği aynı Idempotency-Key ve aynı gövdeyle tekrarlayın: ödeme açıldıysa mevcut ödeme replayed: true ile döner, açılmadıysa şimdi açılır. Yeni bir anahtarla denemek ikinci bir ödeme açabilir. → Yeniden deneme
İptal ucunda anahtar isteğe bağlıdır; iptali tekrarlamak her durumda güvenlidir. Anahtar gönderirseniz aynı anahtar aynı ödemenin iptalinde ödemenin güncel hâlini replayed: true ile döndürür; aynı anahtar başka bir ödemede ya da başka bir işlemde 409 physical_pos.idempotency_mismatch alır.
İsteği gönderin
POST /api/v1/physical-pos/payments · Idempotency-Key zorunlu
Aşağıdaki istek, cihazda 45,00 TRY'lik peşin bir satış başlatır:
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
IDEMPOTENCY_KEY="7b0c6a1e-2f8d-4c55-9a51-3f0e8d1c2a90" # önce siparişinizle birlikte kaydedin
BODY='{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"4500","currency":"TRY","merchantReference":"ORD-2026-000123"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data-raw "$BODY"- cURL örneği imzayı
lunixi-sign.shile hesaplar. Gövdeyi boşluksuz, kompakt JSON olarak gönderin;Digestbu metinden hesaplanır. → İmza yardımcısı - SDK'lar isteği imzalar, belirsiz bir denemeyi aynı anahtar ve aynı gövdeyle tekrarlar ve sonuç yine belirsizse
PhysicalPosOutcomeUnknownError(PHP:PhysicalPosOutcomeUnknownException) atar. Kart verisine benzeyen alanı ağa çıkmadan reddederler. → Node.js SDK · PHP SDK - Tutar her zaman en küçük birimde dizedir:
"4500"= 45,00 TRY. JSON sayısı (4500) reddedilir. → Ödeme Akışı › Tutarlar
Alanlar
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
operation | string | Evet | SALE (satış). Diğer değerler: PREAUTH_OPEN (ön provizyon) ve REFUND_UNMATCHED (eşleşmesiz iade). |
target | object | Evet | Hedef cihaz; aşağıdaki biçimlerden tam olarak biri. → Hedef cihaz |
amountMinor | string | Evet | Tutar, en küçük birimde (TRY'de kuruş); "4500" gibi kanonik pozitif tam sayı dizesi. |
currency | string | Evet | ISO 4217 kodu (TRY). Cihaz ve banka satırı bu para birimini desteklemelidir. |
merchantReference | string | null | Hayır, önerilir | Kendi sipariş ya da fiş numaranız: boşluksuz yazdırılabilir ASCII, en çok 128 karakter. Aynı satışın iki kez tahsil edilmesine karşı ikinci bir korumadır. → merchantReference |
installmentCount | integer | null | Hayır | Taksit sayısı, 2–36; yalnız SALE'de. Gönderilmez, null ya da 0 ise peşin. Cihaz modelinin sınırı uygulanır. |
startTimeoutSeconds | integer | Hayır | Ödemenin cihazda başlaması için süre, 5–30 saniye. Gönderilmez ya da 0 ise 30. Cihaz modelinin sınırı daha kısaysa o uygulanır. |
terminalAcquirerId | string (UUID) | null | Hayır | Ödemenin geçeceği banka satırı. Gönderilmezse bankayı cihaz seçer. → Banka satırı |
items | array | Hayır | Satış kalemleri; yalnız SALE'de. → Kalemli satış |
allowDuplicateReference | boolean | Hayır | true ise aynı referans denetimleri atlanır. Varsayılan false. → Uyarı |
instrument | string | Hayır | Ödeme aracı; API'den başlatılan ödemede yalnız CARD geçerlidir. Gönderilmezse CARD. |
- Gövdede tanımlanmamış bir alan
400 VALIDATION_ERRORalır.organizationId,merchantIdveenvironmentgönderilmez; organizasyonu ve ortamı imzalı anahtarınız belirler. - Bütün alanların kuralları ve hata kodları: Ödemeler › Ödeme başlatma.
Hedef cihaz
| Biçim | Ne zaman |
|---|---|
{ "deviceId": "…" } | Önerilen. Cihaz listesindeki id değeri. |
{ "externalRef": "…" } | Cihazı kaydederken kendi sisteminizdeki kimliği externalRef olarak verdiyseniz. |
{ "vendorCode": "…", "serialNumber": "…" } | Cihazı üretici kodu ve seri numarasıyla tanıyorsanız; iki alan birlikte gönderilir. |
Hedef yoksa ya da birden çok hedef verildiyse 400 physical_pos.payment.target_invalid (details.reason: none ya da multiple). Bulunamayan, başka organizasyona ya da diğer ortama ait ve emekli cihaz aynı cevabı alır: 404 physical_pos.device.not_found. Mağaza, kasa ya da terminal kimliğiyle hedefleme yoktur. → Ödemeler › Hedef cihaz
merchantReference ve aynı referansla yeni satış
merchantReference kendi sisteminizdeki sipariş ya da fiş numarasıdır. Aynı referansla yeni bir satış (SALE) başlattığınızda iki denetim yapılır:
| Durum | Sonuç |
|---|---|
Son 30 gün içinde aynı referanslı ve sonucu kesinleşmemiş (NOT_STARTED, IN_PROGRESS, UNKNOWN, MANUAL_REVIEW) bir satış var | 409 physical_pos.payment.previous_outcome_unknown, details.previousPaymentId |
Kısa süre içinde (varsayılan 10 dakika) aynı referanslı APPROVED bir satış var | 409 physical_pos.payment.duplicate_reference_recent, details.previousPaymentId |
- Denetim cihazlar arasında yapılır: aynı referansla başka bir cihazda başlatılan satış da yakalanır.
allowDuplicateReference: trueiki denetimi de atlar. Bunu yalnız aynı referansla bilerek ikinci bir tahsilat yapacağınızda kullanın.- Kural ters işlemlere ve diğer işlemlere uygulanmaz.
- Önceki ödemeyi
details.previousPaymentIdile okuyabilir ya da listedemerchantReferencesüzgeciyle arayabilirsiniz.
Aynı satış için her zaman aynı merchantReference'ı kullanın. Bir satışın bütün denemelerinde (ağ hatasından sonraki tekrar, cihaz meşgulken yeniden başlatma) referansı değiştirmeyin; bu denetim ancak böyle çalışır.
previous_outcome_unknown aldığınızda allowDuplicateReference kullanmayın. Önceki ödemenin sonucu belli değildir ve para çekilmiş olabilir; önceki ödemenin sonucunu bekleyin.
Kart verisi gönderilmez
Kart cihazda okunur; API kart numarası, son kullanma tarihi, güvenlik kodu ya da manyetik şerit verisi almaz.
- Gövdede ya da sorgu dizesinde kart verisine benzeyen bir alan adı (
pan,cardNumber,cvv,expiry,track2gibi) bulunursa istek400 physical_pos.payment.card_data_rejectedalır. - Serbest metin alanlarında (
merchantReference, kalem adıitems[].name,items[].taxGroupCode) kart numarasına benzeyen bir değer de aynı kodu alır. details.fieldyalnız alanın yolunu verir (ör.items[1].name); gönderdiğiniz değer yanıta, kayıtlara ya da webhook'lara yazılmaz.- Kalem adındaki 13 ya da 14 haneli, kontrol hanesi geçerli barkod kart numarası sayılmaz. → Kalemler › Barkod
Yanıtlarda kart bilgisi yalnız maskeli numara (cardMasked: ilk 6 ve son 4 hane ya da yalnız son 4 hane), kart markası ve okuma biçimi olarak bulunur.
Kalemli satış
Satışı ürün satırlarıyla başlatmak için items dizisini gönderirsiniz. Kalemler ödeme okunduğunda vergi dökümüyle döner ve kalem bazlı iadeye olanak verir.
{
"operation": "SALE",
"target": { "deviceId": "00000000-0000-0000-0000-000000000401" },
"amountMinor": "4500",
"currency": "TRY",
"merchantReference": "ORD-2026-000124",
"items": [
{ "lineNo": 1, "name": "Çay", "quantityMilli": 2000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV10", "lineTotalMinor": "3000", "barcode": "8690000000005" },
{ "lineNo": 2, "name": "Simit", "quantityMilli": 1000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV1", "lineTotalMinor": "1500" }
]
}- Kalemleri yalnız
SALE'de gönderin; en çok 500 satır. Kalemsiz satışta alanı hiç göndermeyin, boş dizi reddedilir. lineNo1'den başlar ve boşluksuz artar.quantityMillimiktar × 1000'dir: 1 adet =1000, 1,5 kg =1500.unitPriceMinorbütün vergiler dahil birim fiyattır. Vergi tutarı göndermezsiniz; vergitaxGroupCode'dan hesaplanır.lineTotalMinor=quantityMilli × unitPriceMinor / 1000, yarım yukarı yuvarlanır ve birebir aynı olmalıdır.- Satırların
lineTotalMinortoplamıamountMinor'a eşit olmalıdır.
Kural bozulursa istek 400 physical_pos.fiscal_document.items_invalid alır; details.field alanın noktalı yolunu (items.0.quantityMilli gibi), details.reason sebebi verir. Tanınmayan vergi grubu 422 physical_pos.fiscal_document.unsupported (tax_group_unsupported) alır. Vergi grupları, birim kodları ve kalem görünümü: Kalemler ve Kalem Bazlı İade.
Adım 3 — Yanıtı anlayın
Yanıt ödemenin kabul edildiğini söyler, ödendiğini değil. Kart henüz okunmamıştır; sonuç asenkron gelir.
| HTTP | data.replayed | Anlamı |
|---|---|---|
202 Accepted | false | Yeni ödeme açıldı; paymentStatus: "NOT_STARTED". Komut cihaza gönderilir. |
200 OK | true | Bu anahtarla bu gövde daha önce gönderilmiş; yeni ödeme açılmadı. Ödemenin güncel hâli döner: durum NOT_STARTED dışında, ör. APPROVED olabilir. |
{
"status": "success",
"code": "SUCCESS",
"data": {
"payment": {
"paymentId": "01900000-0000-7000-8000-000000000501",
"rootPaymentId": "01900000-0000-7000-8000-000000000501",
"originalPaymentId": null,
"origin": "API",
"operation": "SALE",
"paymentStatus": "NOT_STARTED",
"statusReason": null,
"outcomeConflict": false,
"resolvable": false,
"deviceId": "00000000-0000-0000-0000-000000000401",
"logicalTerminalId": "00000000-0000-0000-0000-000000000301",
"terminalAcquirerId": null,
"channel": "APP2APP",
"vendorReference": "01900000000070008000000000000501",
"amountMinor": "4500",
"approvedAmountMinor": null,
"currency": "TRY",
"installmentCount": null,
"instrument": "CARD",
"merchantReference": "ORD-2026-000123",
"reversedMinor": "0",
"capturedMinor": "0",
"reversalReservedMinor": "0",
"pendingReversalId": null,
"reversalStatus": "NONE",
"expiresAt": "2026-01-02T09:00:30.000Z",
"resultDeadlineAt": "2026-01-02T09:03:30.000Z",
"completedAt": null,
"settledAt": null,
"settlementBatchNo": null,
"createdAt": "2026-01-02T09:00:00.000Z",
"updatedAt": "2026-01-02T09:00:00.000Z",
"rowVersion": 2,
"historySeq": 1,
"tender": {
"tenderStatus": "PENDING",
"cardMasked": null,
"cardBrand": null,
"entryMode": null,
"acquirerCode": null,
"authCode": null,
"rrn": null
},
"items": [],
"refundItems": []
},
"replayed": false
},
"statusCode": 202,
"requestId": "00000000-0000-0000-0000-000000000000"
}Bu adımda saklamanız gereken alanlar:
| Alan | Neden |
|---|---|
paymentId | Ödemeyi okumak, webhook'u siparişinizle eşleştirmek, iptal ve ters işlem için. |
paymentStatus | Ödemenin para açısından durumu; kararlarınızı yalnız bu alana göre verin. |
expiresAt | Ödemenin cihazda başlaması için son an. Bu sürede başlamazsa ödeme EXPIRED olur. |
resultDeadlineAt | Sonucun beklendiği son an. Sonuç gelmezse ödeme UNKNOWN olur. |
historySeq | Webhook'ların sırasını doğrulamak için. → Sıra ve tekrar |
Kalemli satışta bile başlatma yanıtında items boş dizidir; kalemleri GET /payments/{paymentId} ile okursunuz. Ödeme nesnesinin bütün alanları: Ödemeler › Ödeme nesnesi.
Durumlar. Ödeme NOT_STARTED → IN_PROGRESS (cihaz kartı ya da banka cevabını bekliyor) üzerinden son durumlarından birine geçer:
| Son durum | Para |
|---|---|
APPROVED | Çekildi. |
PARTIALLY_APPROVED | İstenenden az çekildi; çekilen tutar approvedAmountMinor. |
DECLINED, CANCELLED, EXPIRED, FAILED | Çekilmedi. |
UNKNOWN ve MANUAL_REVIEW son durum değildir: para çekilmiş olabilir. → Sonuç belirsiz olursa. Durumların ve statusReason değerlerinin tamamı: Ödeme Akışı › Ödeme durumları.
Adım 4 — Sonucu alın
Webhook ile (önerilen)
- Panelde Webhook'lar sayfasında Fiziksel POS ürününü seçerek bir endpoint oluşturun ve
physical_pos.*olaylarına abone olun. → Webhook Kurulumu - Teslimatın imzasını gövdeyi ayrıştırmadan, ham gövde üzerinde doğrulayın. → Webhook Olayları › İmza doğrulama
- Olayı
data.paymentIdile ödemenize,data.merchantReferenceile siparişinize eşleştirin. - Siparişi
data.paymentStatus'a göre güncelleyin:
| Olay | Ne yapmalı |
|---|---|
physical_pos.payment.approved | Satışı tamamlayın. Kısmi onay için partially_approved gelir; çekilen tutar approvedAmountMinor. |
physical_pos.payment.declined, .cancelled, .expired, .failed | Para çekilmedi. Müşteriden başka bir kartla ödeme almak için yeni bir ödeme (yeni Idempotency-Key) başlatabilirsiniz. |
physical_pos.payment.unknown, .manual_review | Yeniden tahsil etmeyin. → Sonuç belirsiz olursa |
- Ödemenin başlatılması ve cihazda başlaması (
NOT_STARTED,IN_PROGRESS) için webhook gönderilmez. - Aynı olay birden çok kez gelebilir;
idile tekilleştirin. Sıra garanti değildir; elinizdekinden küçükdata.historySeqtaşıyan olayı yok sayın. - Webhook bankanın onay kodunu, RRN değerini ve kalemleri taşımaz; bunlar için ödemeyi okuyun.
Olay listesi ve yük alanları: Webhook Olayları.
Durum sorgulayarak
Webhook alamıyorsanız ya da bir webhook'tan şüphe ediyorsanız ödemeyi okuyun:
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501"
lunixi_sign GET "$REQ_PATH"
curl "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"Node: await lunixi.physicalPos.getPayment(paymentId) · PHP: $lunixi->physicalPos()->getPayment($paymentId) · Python: lunixi.physical_pos().get_payment(payment_id) · Java: lunixi.physicalPos().getPayment(paymentId)
- Ödeme son durumuna geçene kadar kısa aralıklarla (ör. 2 saniyede bir) okuyun. Ödeme okumaları oran sınırına girmez.
resultDeadlineAtanına kadar sonuç beklenir. Bu andan sonra sonuç gelmediyse ödemeUNKNOWNolur; okumayı daha seyrek sürdürün.- Zaman aşımı başarısızlık değildir: sonuç süresi geçen ödeme
DECLINEDdeğilUNKNOWNolur.
Süreler
| Süre | Değer |
|---|---|
Başlatma süresi (expiresAt) | startTimeoutSeconds: 5–30 saniye, varsayılan 30. Ö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. |
| Belirsiz sonuç bekletmesi | Varsayılan 10 dakika; cihaz bu sürede yeni ödeme almaz. |
Bütün süreler: Ödeme Akışı › Süreler.
Sonuç belirsiz olursa
Aynı satış için yeni bir Idempotency-Key ile ASLA yeni ödeme başlatmayın. Sonuç belirsizken para çekilmiş olabilir; yeni anahtar müşterinizden iki kez tahsilat yapabilir. Lunixi belirsiz ödemeyi hiçbir zaman otomatik olarak yeniden tahsil etmez.
| Durum | Ne yapmalı |
|---|---|
Başlatma isteğine yanıt alamadınız (zaman aşımı, bağlantı kopması, 5xx) ya da SDK PhysicalPosOutcomeUnknownError / PhysicalPosOutcomeUnknownException attı | İsteği aynı Idempotency-Key ve aynı gövdeyle tekrarlayın. Ödeme açıldıysa 200, replayed: true ile güncel hâli döner; açılmadıysa şimdi açılır. Ödemeyi GET /payments?merchantReference=… ile de bulabilirsiniz. |
Ödeme UNKNOWN (physical_pos.payment.unknown) | Bekleyin. Sonuç otomatik olarak doğrulanır; kesinleşirse ödeme son durumuna geçer ve webhook gönderilir. Bu sürede (varsayılan 10 dakika) cihaz yeni ödeme almaz: 409 physical_pos.payment.device_busy (unknown_outcome_hold). |
Ödeme MANUAL_REVIEW (physical_pos.payment.manual_review) | Ödemeyi panelden kanıtla çözün (banka ekstresi, gün sonu raporu, cihaz fişi gibi). Bu işlemin API ucu yoktur. Cihaz yeniden ödeme alabilir. |
Aynı referansla yeni satış 409 physical_pos.payment.previous_outcome_unknown aldı | Önceki ödeme (details.previousPaymentId) sonuçlanmadı. Sonucunu bekleyin; allowDuplicateReference: true göndermeyin. |
- Belirsiz ödeme iptal edilemez (
409 physical_pos.payment.not_cancellable,outcome_unknown) ve geri alınamaz (409 physical_pos.payment.not_reversible,root_not_approved). - Belirsiz ödemelerinizin listesi: İşlemler › Sonucu belirsiz ödemeler. Akışın ayrıntısı: Ödeme Akışı › Sonucu belirsiz ödeme.
Yeniden deneme
| Hata | Ne yapmalı |
|---|---|
409 physical_pos.payment.device_busy, 409 physical_pos.payment.device_not_payable (pairing_hold) | details.retryAfterSeconds kadar bekleyip aynı Idempotency-Key ile yeniden deneyin. |
409 physical_pos.payment.device_offline | Cihaz ödemeye hazır olduğunda yeniden başlatın; ödeme kuyruğa alınmaz. Kayıt açılmadığı için aynı Idempotency-Key'i kullanabilirsiniz. → Cihazın ödemeye hazır olması |
503 physical_pos.presence.unavailable | Cihazın durumu o an doğrulanamıyor. Aynı Idempotency-Key ile, geri çekilerek ve sınırlı sayıda (ör. 1, 2, 4 ve 8 saniye arayla en çok 5 kez) yeniden deneyin; sürerse destekle iletişime geçin. |
503 physical_pos.signing.unavailable, 503 physical_pos.service.busy, 503 physical_pos.service.clock_skew, diğer 5xx ve zaman aşımı | Aynı Idempotency-Key ile, geri çekilerek ve sınırlı sayıda (ör. 1, 2, 4 ve 8 saniye arayla en çok 5 kez) yeniden deneyin; sürerse destekle iletişime geçin. |
Diğer 4xx hatalar yeniden denemeyle düzelmez; isteği düzeltin.
Oran sınırı
Ödeme yazmaları (başlatma, ters işlem ve iptal) organizasyonunuz ve API anahtarınız başına 60 saniyede en çok 120 istek ile sınırlıdır; üç uç aynı sayacı paylaşır. Ödeme okumaları, işlem listesi, raporlar ve gün sonu kayıtları sınırlanmaz.
Sınır aşılırsa istek 429 RATE_LIMITED alır; Retry-After başlığı ve details.retryAfterSeconds beklemeniz gereken saniyeyi verir. Yönetim uçlarının sınırları: Ortak Kurallar › Oran sınırı.
Sık hatalar ve çözümleri
| Hata | Sebep | Çözüm |
|---|---|---|
400 physical_pos.payment.card_data_rejected | Gövdede kart verisine benzeyen alan adı ya da serbest metinde kart numarasına benzeyen değer. | details.field'daki alanı kaldırın ya da düzeltin. → Kart verisi |
400 physical_pos.payment.amount_invalid | Tutar JSON sayısı, sıfır ya da kanonik olmayan dize. | Tutarı "4500" gibi dize olarak gönderin. |
400 physical_pos.payment.target_invalid · 400 physical_pos.fiscal_document.items_invalid | İç içe alanlardan biri (target.*, items.N.*) eksik, türü yanlış ya da kuralı bozuk. | details.field noktalı yolu (items.0.quantityMilli gibi), details.reason sebebi verir. Yanıt ilk hatayı döner; düzeltip yeniden gönderin. |
400 physical_pos.idempotency.key_required | Idempotency-Key başlığı yok. | Her ödeme için yeni bir UUID gönderin. → Idempotency-Key |
403 physical_pos.environment.test_key_read_only | Test anahtarıyla ödeme başlatıldı. | Canlı anahtarı kullanın. |
409 physical_pos.payment.device_offline | Cihaz ödemeye hazır değil (presence.decision: "NOT_READY_DEVICE"). | Cihazın açık, ağa bağlı ve Lunixi uygulamasının çalıştığını kontrol edin; sebep presence.notReadyReason'da. → Adım 1 |
503 physical_pos.presence.unavailable | Cihazın durumu o an doğrulanamıyor (UNVERIFIABLE); sebep cihazınızda değil. | Aynı anahtarla, geri çekilerek yeniden deneyin. → Yeniden deneme |
409 physical_pos.payment.device_busy | Cihazda yürüyen ödeme, belirsiz sonuç bekletmesi ya da gün sonu var. | details.retryAfterSeconds sonra aynı anahtarla yeniden deneyin. |
409 physical_pos.payment.device_not_payable · 409 physical_pos.payment.terminal_not_payable | Cihaz ya da terminal aktif değil, doğrulanmamış ya da cihaz terminale bağlı değil. | details.reason'a bakın. → Cihaz ve terminal |
422 physical_pos.payment.operation_unsupported | capability_undefined: cihaz modelinin ödeme yetenek tanımı yok. channel_unset: haberleşme kanalı tanımlı değil. | details.reason'a bakın; ödeme kaydı oluşmaz. |
409 physical_pos.payment.previous_outcome_unknown | Aynı referanslı önceki satış sonuçlanmadı. | Önceki ödemenin sonucunu bekleyin; allowDuplicateReference kullanmayın. |
409 physical_pos.idempotency_mismatch | Anahtar başka bir gövde ya da işlemle kullanılmış. | Aynı ödemenin tekrarında gövdeyi değiştirmeyin; yeni ödemede yeni anahtar kullanın. |
429 RATE_LIMITED | 60 saniyede 120 ödeme yazması aşıldı. | Retry-After kadar bekleyin. → Oran sınırı |
Bütün kodlar: Hata Kodları.
Sonraki adımlar
- Komutu cihaza ulaşmadan ödemeyi iptal etmek: Ödemeler › İptal
- Onaylanmış ödemeyi void ya da iade etmek: Ödemeler › Ters işlem
- Kalem bazlı iade: Kalemler › Kalem bazlı iade
- Ödemeleri ters işlemleriyle listelemek: İşlemler
- Gün sonu ve void kuralı: Ödeme Akışı › Gün sonu ve void · Gün Sonu Kayıtları
- Satış ve vergi özetleri: Raporlar