Sağlayıcılar
Metropol Kart

Metropol Kart

Metropol Kart, Lunixi Yemek Kartı ürünündeki sağlayıcılardan biridir. Ortak sağlayıcı seçimi, API ve form sözleşmesi için Yemek Kartı rehberini kullanın. Bu sayfa Metropol bağlantısına özgü QR, iade ve rapor kurallarını açıklar.

Metropol Kart, MEAL_CARD yöntemiyle QR veya kısa kod üzerinden ödeme alır. Alıcı kodu Metropol uygulamasında onaylar. QR üretimi ödeme başarısı değildir; başarı, platform sağlayıcıdan sonucu doğruladığında oluşur.

Fiziksel POS'ta QR gösterme ve NFC kart UID okuma, web/form akışından ayrı Fiziksel POS yemek kartı sözleşmesi üzerinden yürür. Android terminal uygulaması 0.1.4 bu komutları işler ve kasa PIN formunda sunucunun sunduğu sağlayıcı/QR/NFC seçimiyle ödeme başlatır; gerçek cihaz ve Metropol sandbox kabulü ayrıca doğrulanır. Bu sayfadaki web/form isteklerine NFC UID eklemeyin.

Metropol bağlantısı test ortamı kapsamındadır. Canlı QR/web kullanım sözleşmesi ve canlı adres doğrulanmadan canlı tahsilat açılmaz. Hesabınıza sunulan yöntemleri ve sağlayıcıları GET /payments/methods yanıtından okuyun.

Bağlantıyı hazırlayın

Panelde Yemek Kartları → Metropol Kart bağlantısını test ortamında oluşturun. Sağlayıcıdan aldığınız kimlik ve terminal bilgilerini girin; QR / kısa kodla ödeme yetkisini açık tutun. Form kullanacaksanız Form Ayarları'nda Yemek Kartı yöntemini ve Metropol bağlantısını etkinleştirin.

Bağlantı alanları: Consumer ID, Consumer Name, Reference No, Access Key, AES Key, Merchant Code ve Terminal Code. Bu değerleri yalnız paneldeki sağlayıcı bağlantısına kaydedin; ödeme gövdesine veya tarayıcıya göndermeyin.

Bu sürüm Metropol Resto (TRY, tek çekim) içindir. Kart numarası, CVV, 2D/3D seçimi, taksit veya ön provizyon gönderilmez. Normal iptal, tam/kısmi iade ve günlük işlem mutabakatı da test ortamında desteklenir; bağlantının ilgili işlem yetkileri açık olmalıdır.

API ile ödeme alın

İsteği merchant sunucunuzdan mevcut Bearer ve istek imzalama sözleşmesiyle POST /payments/direct/payment ucuna gönderin. Idempotency-Key zorunludur; aynı ödeme isteğinin tekrarlarında aynı anahtarı kullanın. Merchant Bearer token'ını tarayıcıya koymayın.

{
  "paymentMethod": "MEAL_CARD",
  "amount": "10000",
  "currency": "TRY",
  "orderId": "ORDER-METROPOL-001",
  "mealCard": {
    "providerCode": "METROPOL"
  }
}

amount, kuruş cinsinden rakam dizisidir; "10000", 100,00 TRY anlamına gelir. Yöntem listesindeki bir bağlantıyı seçiyorsanız dönen optionId değerini üst seviyede gönderin. mealCard içindeki ek alanlar sağlayıcının inputFields tanımına uymalıdır; Metropol QR akışında alıcıdan ek alan istenmez.

Başlatma yanıtının data bölümünde açık müşteri aksiyonu gelir:

{
  "paymentId": "<payment-id>",
  "orderId": "ORDER-METROPOL-001",
  "status": "PROCESSING",
  "paymentMethod": "MEAL_CARD",
  "providerCode": "METROPOL",
  "action": {
    "id": "<action-id>",
    "type": "DISPLAY",
    "expiresAt": "2026-11-05T12:01:15.000Z",
    "display": {
      "qrCode": "<provider-qr-payload>",
      "shortCode": "012345"
    }
  }
}

Örnekteki kodlar temsildir. action.display.qrCode metnini değiştirmeden yerel bir QR kütüphanesiyle çizin; bu alan bir resim adresi değildir. Alıcı başka cihazdan QR'ı okutur veya aynı telefonda shortCode değerini Metropol uygulamasına girer. Baştaki sıfır korunmalıdır. DISPLAY aksiyonu için confirm veya resend çağrısı yapılmaz.

Sonucu merchant sunucunuzdan GET /payments/:id ile takip edin; mevcut ödeme webhook akışınızı kullanmaya devam edin. Yalnız platformun kesin başarılı ödeme durumunda siparişi ödendi sayın. PROCESSING ve NEEDS_RECONCILIATION bekleyen/belirsiz sonuçtur.

Checkout Formu ile ödeme alın

Mevcut Checkout Formu entegrasyonunu kullanın. Form açılışında sunulan Yemek Kartı → Metropol Kart seçeneği, mevcut checkout token'ı ve session proof ile POST /payments/form/payment isteği gönderir:

{
  "token": "<checkout-token>",
  "checkoutSessionProof": "<session-proof>",
  "paymentMethod": "MEAL_CARD",
  "mealCard": { "providerCode": "METROPOL" },
  "browserFingerprint": "<browser-fingerprint>",
  "paymentChannel": "WEB"
}

Form isteğine tutar, sipariş veya alıcı bilgisi eklemeyin: platform bunları checkout kaydından okur. Form dönen QR/kısa kodu ve süre sayacını gösterir. Yeniden render veya sekmeyi kapatıp açma yeni QR isteği oluşturmaz.

Tek yemek kartı sağlayıcısı Metropol olsa da alıcı önce Metropol Kart satırını seçer; yalnız Yemek Kartı bölümünü açmak QR isteği oluşturmaz.

Form, kayıtlı ödeme durumunu POST /payments/form/payment/status ile okur:

{
  "token": "<checkout-token>",
  "checkoutSessionProof": "<session-proof>"
}

Yanıtın data bölümü aynı ödeme kimliği, durum ve varsa açık aksiyonu içerir. Bu uç sağlayıcıya ödeme veya sorgu isteği göndermez; Metropol sorgusunu sunucu görevi yürütür. Tarayıcıda sağlayıcı anahtarı veya merchant Bearer bulunmaz.

Kesin başarılı ödeme sonrasında form, kayıtlı geçerli callbackUrl adresine data.merchantCallback içindeki imzalı alanlarla bir kez POST yapar. Bu alanlar mevcut callback imza sözleşmesini kullanır. Adres yoksa başarı mesajı formda kalır; bekleyen/belirsiz sonuç başarı olarak yönlendirilmez.

Süre dolumu ve belirsiz sonuç

Kodun son geçerliliği expiresAt alanıdır. Süre dolunca kodu gizleyin ve sonucu izlemeye devam edin; sayaç tek başına ödeme başarısızlığı kanıtı değildir. Ağ hatası, eksik yanıt veya sağlayıcıda “kayıt bulunamadı” sonucu yeni ödeme başlatma gerekçesi değildir. Özellikle aynı referansla tekrar QR üretimine güvenmeyin: sağlayıcı aynı referansı yeni işlem olarak kabul edebilir.

Yeni ödemeleri durdurmak için Form Ayarları içindeki Yemek Kartları yöntemini veya Metropol bağlantısını pasifleştirin. Pasif bağlantının kayıtlı ödemelerine ait sorgu, yetkili iade ve API mutabakatı devam eder; bağlantı yeni ödeme adaylarına eklenmez. Silinmiş bağlantılar veya erişilemeyen sağlayıcı anahtarları bu kapsama girmez.

İptal ve iade

Hem API hem Checkout Formu ile alınan ödeme için panelde ödeme detayındaki İade işlemini veya merchant sunucunuzdan mevcut iade sözleşmesini kullanın: POST /payments/:id/refund. Panel oturumu ya da imzalı API isteği, payment:refund yetkisi ve bir Idempotency-Key gerekir. Gövdedeki paymentIntentId, URL'deki ödeme kimliğiyle aynı olmalıdır. Kalan tutarın tamamını iade etmek için amount göndermeyin. Kısmi iade örneği:

{
  "paymentIntentId": "<payment-id>",
  "amount": "2500",
  "reason": "Bir ürün iade edildi"
}

Örnek 25,00 TRY iade eder. Birden fazla kısmi iadenin toplamı çekilen tutarı aşamaz. Her yeni iade için ayrı anahtar, aynı isteğin tekrarında aynı anahtar kullanılır. Metropol aynı batch içindeki tam iadeyi iptal, diğer iadeleri iade olarak sınıflandırır; ikisi de bu iade akışını ve ReturnType=1 çağrısını kullanır. Platformda iade kaydı, iade tutarı ve iade webhook'u oluşur. /void ön provizyon içindir ve Metropol QR ödemesinde kullanılmaz. Teknik iptal (ReturnType=2) gönderilmez. Form, alıcının tarayıcısından iade başlatmaz.

İade veya iptal yanıtı belirsizse işlem mutabakata bırakılır; aynı ödeme için yeni anahtarla yeniden iade denemeyin. Başarılı satış sorgusu, iadenin yapıldığı anlamına gelmez. Metropol'ün belgelenmiş ayrı bir iade sorgusu olmadığı için kayıp yanıt sağlayıcı teyidi gerektirebilir. Sonucu ödeme kaydı ve mevcut iade webhook'larıyla izleyin.

Günlük işlem mutabakatı

Panelde Metropol bağlantısının mutabakat tipini API seçin. Platform kapanmış günlerin raporlarını otomatik alır, bütün sayfaları doğrular ve yalnız kendi kayıtlarıyla sahipliğini kanıtladığı web ödemelerini eşleştirir. Aynı işyeri raporundaki fiziki POS veya diğer işlemler, web ödemesi olarak atanmaz. Tutar/durum uyuşmazlıkları operasyon incelemesine açılır.

Bu rapor satış/iptal/iade kanıtıdır; komisyon, net ödeme veya banka transferi teyidi değildir ve hakedişi otomatik serbest bırakmaz. Sağlayıcı saat dilimi vermiyorsa kayıt rapor günü hassasiyetindedir. Pasif bağlantının geçmiş işlemleri için de API raporu alınabilir; mutabakat seçimi ve sağlayıcı anahtarlarına erişim korunmalıdır. Canlı ortam desteği, sağlayıcı kabulü tamamlanana kadar kapalıdır.

Mutabakat ekranındaki Sağlayıcı işlem raporları bölümünde kaynak günü, rapor aşamasını, son başarılı koşumu ve hata/tekrar bilgisini görebilirsiniz. Terminal, referans, tutar ve sahiplik bilgisiyle son 50 satır önizlenir; uyuşmazlıklar mevcut vaka akışında izlenir. Ortak platform hesabındaki atanmamış satırlar başka merchant'lara gösterilmez.