Web SDK — Genel Bakış

Lunixi tarayıcı tarafında sekiz ayrı SDK yayınlar. Hepsi aynı çekirdeği paylaşır; farkları ne yaptıkları ve nasıl kimlik doğruladıklarıdır.

SDK	Ne yapar	Sayfası
`checkout`	Ödeme formu	Checkout Form
`field`	Barındırılan kart alanı (PCI kapsamını daraltır)	Kart Alanı
`identity`	Cihaz ve davranış telemetrisi	Identity Web SDK
`kyc`	Rehberli kimlik doğrulama akışı	KYC SDK
`portal`	Müşteri portalı — plan, abonelik, kart	Portal SDK
`marketplace`	Alt bayi başvuru ve yönetim akışı	Marketplace SDK
`paymentLink`	Linkle ödeme ekranı — `pay.lunixi.com` üzerinde Lunixi tarafından çalıştırılır, sizin kurmanız gerekmez; sitenize gömme çok yakında	Ödeme Sayfası
`loader`	Diğerlerini tembel yükleyen giriş noktası	Aşağıda

Loader — tek script, hepsi

Her SDK'yı ayrı <script> ile yüklemek zorunda değilsiniz. Loader'ı koyarsınız, çağırdığınız modül ilk kullanımda indirilir.

<script src="https://cdn.lunixi.com/lunixi-loader.min.js"></script>

// lunixi-kyc.min.js bu satırda indirilir, öncesinde değil
await Lunixi.kyc.mount('#kyc', { … });

Loader bir vekil (proxy) kurar: Lunixi.<modül>.<metot>(...) çağrısı modülü indirir, sonra çağrıyı iletir. Aynı modül ikinci kez çağrılırsa tekrar indirilmez.

CDN adresini değiştirmeniz gerekirse yükleme öncesi window.Lunixi = { config: { cdnBaseUrl: '…' } } tanımlarsınız; loader onu kullanır. Tanımlamazsanız kendi <script src> adresinden türetir.

Dört entegrasyon modu

SDK'lar tek bir kullanım biçimi dayatmaz. Ne kadar kontrol istediğinize göre seçersiniz:

Mod	Ne verir	Çağrı
Mode 0 — Katalog	Publishable key ile salt-okunur veri; oturum yok, anonim ziyaretçi	`Lunixi.portal.catalog({...})`
Mode 1 — Hazır UI	Tam ekranı biz çizeriz, siz bir DOM hedefi verirsiniz	`.mount(target, {...})` · `.form({...})`
Mode 2 — Headless	UI'ı siz yazarsınız, SDK yalnız veri katmanı	`.create({...})`
Mode 3 — Hibrit	Ekranın parçalarını tek tek monte edersiniz	`Lunixi.portal.plans.mount(...)`

Mode 1 ile Mode 2 arasında geçiş yapabilirsiniz. Hızlı başlamak için hazır UI ile çıkar, marka ihtiyacınız büyüyünce aynı SDK'nın headless istemcisine geçersiniz — uçlar ve oturum modeli değişmez.

.mount() ile .form() farkı: mount doğrudan monte eder, form bir tutamaç döndürür (sonradan unmount edebilmeniz için).

Kimlik doğrulama — SDK'ya göre değişir

Bu sayfanın en önemli tablosu budur. Tarayıcıda secret key hiçbir zaman bulunmaz; her SDK'nın kendi güvenli yolu vardır.

SDK	Tarayıcıda taşınan	Nasıl doğrulanır
`portal` katalog (Mode 0)	`Bearer mk_live_pk_…`	Publishable key + `Origin` eşleşmesi
`kyc`	Publishable key → imzalı oturum	`POST /api/v1/kyc/sdk/init`
`identity`	Sizin sunucunuzdan basılan oturum token'ı	`sessionBootstrapUrl` (sizin ucunuz)
`portal` (Mode 2)	`X-Portal-Session` (JWT)	Portal oturumu
`marketplace`	`X-Marketplace-Token` (`mp_…`)	Bearer değil — portal-token deseni
`checkout`	Checkout token + session-proof çerezi	Ödeme oturumu
`paymentLink`	Anahtar yok — linkin kısa kodu; ödeme başlatırken bot kontrolü (Turnstile) ve kısa ömürlü ödeme oturumu çerezi, ödeme adımında checkout token	Linkle ödeme oturumu (`/api/public/v1/pay/*`)

Publishable key nasıl korunur

Publishable key gizli değildir — sayfa kaynağında görünür. Koruma anahtarın kendisinde değil, nereden kullanıldığındadır:

Anahtar mk_{ortam}_pk_… biçimindedir; sunucu öneki kontrol eder.
İstek Origin başlığı taşımak zorundadır — bunu tarayıcı koyar, sayfadaki JavaScript sahteleyemez.
Origin, o anahtar için kayıtlı izinli origin listesinde tam eşleşmelidir.
Eşleşmezse 401.

⚠️

Yani anahtarınız çalınsa bile sizin domain'inizin dışından kullanılamaz. Ama izinli origin listesini geniş tutarsanız (* benzeri kalıplar, test domain'lerini canlıda bırakmak) bu korumayı kendiniz zayıflatırsınız.

Barındırılan kart alanı (`field`)

Kart numarasının sayfanıza hiç girmemesi gereken durumlar için ayrı bir SDK vardır: alan bir iframe olarak fields.lunixi.com üzerinden gömülür. Kart verisi sizin DOM'unuza hiç değmez, dolayısıyla PCI kapsamınız daralır.

Checkout SDK'sından Lunixi.checkout.createCardField(...) ile de erişilir.

Ortak davranış

Tembel yükleme — ağır UI (React + akış ekranları) yalnız Mode 1'de ve ilk mountta indirilir. Headless kullanırsanız bundle'ınıza girmez.
Fail-open değil — SDK çağrıları hata durumunda sessizce "geçti" dönmez, hata fırlatır. Yedek davranışı siz kurgularsınız.
Ortam ayrımı — anahtarınız hangi ortamda üretildiyse SDK o ortama konuşur.

🚫

Secret key'i asla tarayıcıya koymayın. Sayfada bulunabilecek tek anahtar publishable key'dir. Bir SDK sizden secret key istiyorsa yanlış modu kullanıyorsunuzdur.

Nereden başlamalı

Ödeme alacaksanız → Checkout Form
Kimlik doğrulatacaksanız → KYC SDK
Abonelik/plan gösterecek veya müşteri portalı açacaksanız → Portal SDK
Alt bayi kabul edecekseniz → Marketplace SDK
Cihaz sinyali toplayacaksanız → Identity Web SDK

Genel Bakış Kart Alanı