Fiziksel POS
Hızlı Başlangıç: İlk Ödeme

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.

Bu uçları kim çağırır?Dış API (s2s)
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ıca Digest. 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 anahtar 403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar 403 API_INSUFFICIENT_SCOPE alı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

GereksinimAçı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.decisionAnlamıÖdeme başlatırsanız
READYCihaz bağlı ve ödeme almaya hazır.Hazır olma denetiminden geçer.
NOT_READY_DEVICECihaz 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
UNVERIFIABLELunixi 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 READY saymayın. presence okunamadıysa null döner.
  • presence yalnı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.

  1. Her ödeme için yeni bir UUID üretin.
  2. Anahtarı isteği göndermeden önce, siparişinizle birlikte kendi kaydınıza yazın.
  3. İsteği bu anahtarla gönderin. Aynı ödemenin bütün denemelerinde aynı anahtarı ve aynı gövdeyi kullanın.
UçIdempotency-Key
POST /paymentsZorunlu
POST /payments/{paymentId}/reversalsZorunlu
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.

DurumSonuç
Yeni anahtarÖdeme açılır: 202, replayed: false.
Aynı anahtar, aynı gövdeYeni ö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 paymentId de 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.sh ile hesaplar. Gövdeyi boşluksuz, kompakt JSON olarak gönderin; Digest bu 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

AlanTipZorunluAçıklama
operationstringEvetSALE (satış). Diğer değerler: PREAUTH_OPEN (ön provizyon) ve REFUND_UNMATCHED (eşleşmesiz iade).
targetobjectEvetHedef cihaz; aşağıdaki biçimlerden tam olarak biri. → Hedef cihaz
amountMinorstringEvetTutar, en küçük birimde (TRY'de kuruş); "4500" gibi kanonik pozitif tam sayı dizesi.
currencystringEvetISO 4217 kodu (TRY). Cihaz ve banka satırı bu para birimini desteklemelidir.
merchantReferencestring | nullHayır, önerilirKendi 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
installmentCountinteger | nullHayırTaksit sayısı, 2–36; yalnız SALE'de. Gönderilmez, null ya da 0 ise peşin. Cihaz modelinin sınırı uygulanır.
startTimeoutSecondsintegerHayı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.
terminalAcquirerIdstring (UUID) | nullHayırÖdemenin geçeceği banka satırı. Gönderilmezse bankayı cihaz seçer. → Banka satırı
itemsarrayHayırSatış kalemleri; yalnız SALE'de. → Kalemli satış
allowDuplicateReferencebooleanHayırtrue ise aynı referans denetimleri atlanır. Varsayılan false. → Uyarı
instrumentstringHayı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_ERROR alır. organizationId, merchantId ve environment gö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çimNe 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:

DurumSonuç
Son 30 gün içinde aynı referanslı ve sonucu kesinleşmemiş (NOT_STARTED, IN_PROGRESS, UNKNOWN, MANUAL_REVIEW) bir satış var409 physical_pos.payment.previous_outcome_unknown, details.previousPaymentId
Kısa süre içinde (varsayılan 10 dakika) aynı referanslı APPROVED bir satış var409 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: true iki 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.previousPaymentId ile okuyabilir ya da listede merchantReference sü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, track2 gibi) bulunursa istek 400 physical_pos.payment.card_data_rejected alı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.field yalnı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" }
  ]
}
  1. Kalemleri yalnız SALE'de gönderin; en çok 500 satır. Kalemsiz satışta alanı hiç göndermeyin, boş dizi reddedilir.
  2. lineNo 1'den başlar ve boşluksuz artar.
  3. quantityMilli miktar × 1000'dir: 1 adet = 1000, 1,5 kg = 1500.
  4. unitPriceMinor bütün vergiler dahil birim fiyattır. Vergi tutarı göndermezsiniz; vergi taxGroupCode'dan hesaplanır.
  5. lineTotalMinor = quantityMilli × unitPriceMinor / 1000, yarım yukarı yuvarlanır ve birebir aynı olmalıdır.
  6. Satırların lineTotalMinor toplamı 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.

HTTPdata.replayedAnlamı
202 AcceptedfalseYeni ödeme açıldı; paymentStatus: "NOT_STARTED". Komut cihaza gönderilir.
200 OKtrueBu 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:

AlanNeden
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.
resultDeadlineAtSonucun beklendiği son an. Sonuç gelmezse ödeme UNKNOWN olur.
historySeqWebhook'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 durumPara
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)

  1. 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
  2. Teslimatın imzasını gövdeyi ayrıştırmadan, ham gövde üzerinde doğrulayın. → Webhook Olayları › İmza doğrulama
  3. Olayı data.paymentId ile ödemenize, data.merchantReference ile siparişinize eşleştirin.
  4. Siparişi data.paymentStatus'a göre güncelleyin:
OlayNe yapmalı
physical_pos.payment.approvedSatışı tamamlayın. Kısmi onay için partially_approved gelir; çekilen tutar approvedAmountMinor.
physical_pos.payment.declined, .cancelled, .expired, .failedPara çekilmedi. Müşteriden başka bir kartla ödeme almak için yeni bir ödeme (yeni Idempotency-Key) başlatabilirsiniz.
physical_pos.payment.unknown, .manual_reviewYeniden 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; id ile tekilleştirin. Sıra garanti değildir; elinizdekinden küçük data.historySeq taşı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.
  • resultDeadlineAt anına kadar sonuç beklenir. Bu andan sonra sonuç gelmediyse ödeme UNKNOWN olur; okumayı daha seyrek sürdürün.
  • Zaman aşımı başarısızlık değildir: sonuç süresi geçen ödeme DECLINED değil UNKNOWN olur.

Süreler

SüreDeğ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ç bekletmesiVarsayı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.

DurumNe 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.

Yeniden deneme

HataNe 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_offlineCihaz ö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.unavailableCihazı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

HataSebepÇözüm
400 physical_pos.payment.card_data_rejectedGö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_invalidTutar 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_requiredIdempotency-Key başlığı yok.Her ödeme için yeni bir UUID gönderin. → Idempotency-Key
403 physical_pos.environment.test_key_read_onlyTest anahtarıyla ödeme başlatıldı.Canlı anahtarı kullanın.
409 physical_pos.payment.device_offlineCihaz ö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.unavailableCihazı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_busyCihazda 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_payableCihaz 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_unsupportedcapability_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_unknownAynı referanslı önceki satış sonuçlanmadı.Önceki ödemenin sonucunu bekleyin; allowDuplicateReference kullanmayın.
409 physical_pos.idempotency_mismatchAnahtar 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_LIMITED60 saniyede 120 ödeme yazması aşıldı.Retry-After kadar bekleyin. → Oran sınırı

Bütün kodlar: Hata Kodları.

Sonraki adımlar