Fiziksel POS
Ödeme İşlemleri
Yemek Kartıyla Satış

Yemek Kartıyla Satış

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

Yemek kartı ödemesi, banka kartı satışıyla aynı uçtan başlatılır: POST /api/v1/physical-pos/payments. Fark üç alandadır: instrument: "MEAL_CARD", ödemenin cihazda nasıl alınacağını söyleyen interaction ve kullanılacak kart sağlayıcı satırı (terminalProviderId). Ödeme banka üzerinden değil, kart sağlayıcısı üzerinden Lunixi sunucusunda yürütülür; durumlar, webhook'lar ve sonucu alma kartlı satışla aynıdır. → Satış (Ödeme Çekme)

Hazırlık:

  1. Kart sağlayıcısının üretici hesabını panelde Entegrasyonlar ekranından ekleyin.
  2. Cihazın bağlı olduğu mantıksal terminale sağlayıcı satırını ekleyin. → Kart Sağlayıcı Satırları
  3. Cihaz modeli yemek kartını desteklemelidir. Desteklemeyen cihaz 422 physical_pos.payment.operation_unsupported (details.reason: instrument_unsupported) alır.

Ödeme yöntemi: interaction

DeğerCihazda ne olur
INSTRUMENT_READCihaz kartı okutmanızı ister (temassız).
CODE_DISPLAYCihaz ekranında bir QR ya da kısa kod gösterir; müşteri kodu kendi kart uygulamasıyla okutup onaylar. Kod yalnız cihaza gönderilir, API yanıtında yer almaz.

Lunixi Android uygulaması

Terminal uygulaması 0.1.4 (5), protokol paketi 3.6.0 kasiyer sağlayıcı ekini tüketir. Önceki 0.1.3'teki Metropol QR gösterme, NFC UID okuma ve sunucudan sonuç gösterme akışlarını korur. Yukarıdaki API isteğinin CODE_DISPLAY değeri cihazda imzalı DISPLAY_CODE komutuna dönüşür. QR yerelde çizilir; kısa kod ve kalan süre gösterilir. INSTRUMENT_READ, standart Android NFC servisi üzerinden desteklenen MIFARE kartın yalnız UID'sini okur. Sağlayıcı anahtarları ve Metropol'e tahsilat çağrıları sunucuda kalır.

Debug cihaz denemesi için LIVE cihaz + operatör sandbox kilidi, sandbox sağlayıcı hesabı, ilgili ödeme yöntemini açan imzalı cihaz ayarı ve terminalin sağlayıcı bağlantısı gerekir. Ürün havuzu da sağlayıcıda tanımlı olmalıdır.

Kasa modunda yetkili kasiyer PIN ile giriş yapıp sunucunun sunduğu sağlayıcı satırını ve QR/NFC yöntemini seçebilir. Seçenekler ekran açılışında ve girişte yenilenen imzalı cihaz GET cashiers yanıtındaki providerPaymentOptions listesinden gelir. Liste boşsa veya alan yoksa sağlayıcı API seçeneği gösterilmez. Cihaz POST cashier-payments isteğine instrument: MEAL_CARD, interaction ve seçilen terminalProviderId ekler; taksit veya kalem göndermez. Banka kartı ve ters işlem isteklerine sağlayıcı seçim alanları eklenmez. Bunlar cihaz kimliği ve kasiyer oturumuyla kullanılan uçlardır; dış yazılımlar bu sayfadaki merchant API'sini kullanmaya devam eder.

Seçim ilk istekten önce kalıcı kayda alınır. Seçenek sonradan kaldırılırsa uygulama başka ödeme yöntemine geçmez. Yanıt kaybolduğunda yeni tahsilat gönderilmez; aynı idempotency kaydı sorgulanır. Liste izin değildir; sunucu ödeme anında yetki, limit, terminal ve sandbox uygunluğunu tekrar denetler. Bu teslim v8 kapsamlı gün sonu veya DEVICE_INFO desteği ilan etmez; onlar ayrı devam işleridir.

⚠️

Bu Android kaynak teslimi gerçek cihaz veya finansal kabul değildir. POS üreticisi standart NFC servisini açmıyorsa üretici okuyucu bağlantısı ayrıca gerekir; NFC'siz cihaz QR gösterebilir. SoftPOS bileşiminde zorunlu cihaz güveni kabulü tamamlanana kadar bu akışlar kapalıdır. Metropol test bakiyesi, QR müşteri onayı, fiziksel kart UID bayt sırası ve sağlayıcı sonucu cihazda doğrulanmalıdır.

Tek komut en fazla bir NFC okuma olayı üretir. Sonuç teslim edilene kadar olay şifreli cihaz outbox'ında tutulur; kart UID'si ekran veya loglara eklenmez. Süre dolumu, ağ kaybı ya da uygulamanın arka plana geçmesi QR/okumayı kapatır; bunlar tahsilatın kesin başarısızlığı anlamına gelmez. Aynı ödemeyi yeniden çekmeyin; sonucu sorgulayın. Sonucu sunucunun OUTCOME_DISPLAY komutu gösterir.

İstek

Satış isteğinin bütün kuralları geçerlidir; şu alanlar eklenir ya da değişir:

AlanTipZorunluAçıklama
operationstringEvetYalnız SALE.
instrumentstringEvetMEAL_CARD.
interactionstringEvetINSTRUMENT_READ ya da CODE_DISPLAY. Kartlı satışta gönderilmez.
terminalProviderIdstring (UUID)KoşulluKullanılacak sağlayıcı satırı. Terminalde bu ödemeye uyan tek etkin satır varsa gönderilmeyebilir. Kartlı satışta gönderilmez.

Yemek kartı ödemesinde installmentCount, items ve terminalAcquirerId gönderilmez.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
BODY='{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"4450","currency":"TRY","instrument":"MEAL_CARD","interaction":"CODE_DISPLAY","terminalProviderId":"00000000-0000-0000-0000-000000000351","merchantReference":"ORD-2026-000124"}'
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: 9d1e3b5a-7c2f-4e8b-a6d0-1f4c8b2e6a93" \
  --data-raw "$BODY"

Yanıt kartlı satıştaki gibi 202 ve paymentStatus: "NOT_STARTED" ile döner; ödemenin instrument alanı MEAL_CARD'dır. → Ödeme Nesnesi

Sağlayıcı satırının seçimi

terminalProviderId göndermezseniz Lunixi, cihazın bağlı olduğu terminalde sağlayıcısı bu ödeme yöntemini (interaction) sunan tek etkin satırı seçer.

DurumSonuç (422 physical_pos.payment.operation_unsupported)
Uyan satır yokdetails.reason: provider_terminal_missing
Birden çok uyan satır varprovider_terminal_ambiguous — terminalProviderId gönderin.
Gönderilen satır başka terminalde, etkin değil ya da bu yöntemi sunmuyorprovider_terminal_not_found
Satırın üretici hesabı etkin değilprovider_account_inactive
Kart okutmada sağlayıcının kart türleri tanımlı değilinstrument_types_undefined

Kodun süresi ve sonuç

CODE_DISPLAY'de kodun bir geçerlilik süresi vardır; süre sağlayıcıya göre değişir. Lunixi bu sürede sağlayıcıyı sorgular:

DurumpaymentStatusstatusReason
Müşteri onayladıAPPROVED—
Kodun süresi doldu, ödeme yapılmadıEXPIREDPROVIDER_CODE_EXPIRED
Sorgu süresi bitti, sonuç kesinleşmediUNKNOWNPROVIDER_CODE_WINDOW_ELAPSED

UNKNOWN ödemeyi yeniden başlatmayın; para çekilmiş olabilir. → Sonucu Belirsiz Ödeme Süresi dolmuş ödemeye sonradan onay gelirse durum değişmez; ödemede outcomeConflict: true olur ve ödemeyi panelde incelersiniz.

İptal ve iade

Yemek kartı satışına void, iade ve kısmi iade yapılabilir. Ters işlem kartlı satıştaki uçla başlatılır ve satışın sağlayıcı satırı üzerinden yürütülür; ters işlem isteğinde interaction ya da terminalProviderId göndermezsiniz.

details.reason (422 physical_pos.payment.operation_unsupported)Anlamı
original_provider_link_missingSatışın sağlayıcı satırı bilgisi bulunamadı.
original_terminal_closedSatışın terminali kapatılmış.

Cihaza ulaşmamış ödemeyi başlamadan iptal edebilirsiniz; cihazdaki kart okutma ya da kod ekranı kapanır.

Ödeme webhook'ları ödeme aracını taşımaz. Yemek kartı ödemesini kartlı ödemeden ayırmak için ödemeyi okuyun (instrument). → Ödeme Sorgulama

Hatalar

Satış hatalarına ek olarak:

HTTPcodeNe zaman
400physical_pos.validation.invalidinteraction yok ya da geçersiz; kartlı satışta interaction ya da terminalProviderId gönderildi; yemek kartında terminalAcquirerId gönderildi; terminalProviderId UUID değil (details.field).
400physical_pos.payment.installment_unsupportedYemek kartında taksit (details.reason: instrument).
422physical_pos.payment.operation_unsupportedinstrument_unsupported, instrument_operation_unsupported (SALE dışı işlem), items_instrument_unsupported (kalem gönderildi) ya da sağlayıcı satırı sebepleri.

Bütün kodlar: Hata Kodları.