Yemek Kartıyla Satış
- 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. Ü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.
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:
- Kart sağlayıcısının üretici hesabını panelde Entegrasyonlar ekranından ekleyin.
- Cihazın bağlı olduğu mantıksal terminale sağlayıcı satırını ekleyin. → Kart Sağlayıcı Satırları
- 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ğer | Cihazda ne olur |
|---|---|
INSTRUMENT_READ | Cihaz kartı okutmanızı ister (temassız). |
CODE_DISPLAY | Cihaz 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:
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
operation | string | Evet | Yalnız SALE. |
instrument | string | Evet | MEAL_CARD. |
interaction | string | Evet | INSTRUMENT_READ ya da CODE_DISPLAY. Kartlı satışta gönderilmez. |
terminalProviderId | string (UUID) | Koşullu | Kullanı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.
| Durum | Sonuç (422 physical_pos.payment.operation_unsupported) |
|---|---|
| Uyan satır yok | details.reason: provider_terminal_missing |
| Birden çok uyan satır var | provider_terminal_ambiguous — terminalProviderId gönderin. |
| Gönderilen satır başka terminalde, etkin değil ya da bu yöntemi sunmuyor | provider_terminal_not_found |
| Satırın üretici hesabı etkin değil | provider_account_inactive |
| Kart okutmada sağlayıcının kart türleri tanımlı değil | instrument_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:
| Durum | paymentStatus | statusReason |
|---|---|---|
| Müşteri onayladı | APPROVED | — |
| Kodun süresi doldu, ödeme yapılmadı | EXPIRED | PROVIDER_CODE_EXPIRED |
| Sorgu süresi bitti, sonuç kesinleşmedi | UNKNOWN | PROVIDER_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_missing | Satışın sağlayıcı satırı bilgisi bulunamadı. |
original_terminal_closed | Satışı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:
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.validation.invalid | interaction 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). |
400 | physical_pos.payment.installment_unsupported | Yemek kartında taksit (details.reason: instrument). |
422 | physical_pos.payment.operation_unsupported | instrument_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ı.