Kart Alanı (Hosted Field)

Kendi ödeme ekranınızı çizmek ama kart verisine hiç dokunmamak istediğinizde bunu kullanırsınız. Alan, sayfanıza bir çapraz-origin iframe olarak gömülür; kart numarası ve CVC sizin DOM'unuza hiç girmez.

const field = Lunixi.checkout.createCardField({ /* … */ });
await field.mount('#card-field');

Checkout SDK'sının bir varyantıdır — ayrı script yüklemeniz gerekmez, loader yeterlidir.

Sayfanıza yerleştirme

Alanın çizileceği boş bir <div> açarsınız; SDK içini kendisi doldurur.

<div id="card-field-checkout"></div>
 
<script src="https://cdn.lunixi.com/lunixi-checkout.min.js"></script>
<script>
  const checkout = Lunixi.checkout.createCardField({
    options: {
      token: 'ödeme intent yanıtındaki token',
      Currency: 'TRY',
      Price: '125.00',
      Locale: 'tr',
      force3Ds: '1',
      cardHolderName: 'Demo User',
    },
  });
 
  checkout.mount('#card-field-checkout');
</script>

mount() iki biçimi de kabul eder. Önce getElementById dener, bulamazsa querySelector'a düşer — yani 'card-field-checkout' (çıplak id) ve '#card-field-checkout' (CSS seçici) aynı sonucu verir. Bir DOM elemanı da geçirebilirsiniz.

⚠️

Hedef <div>'i boş bırakın. SDK monte ederken içeriğini temizler; oraya koyduğunuz yer tutucu içerik kaybolur. Yükleme göstergesi istiyorsanız div'in dışına koyun ve mount sonrası gizleyin.

Alanın yüksekliği kart girildikçe değişir (taksit tablosu açılır). Iframe yüksekliğini HEIGHT_CHANGED mesajıyla bildirir; SDK bunu sizin adına uygular, yani div'e sabit height vermeyin.

Taban adresleri değiştirme

Yerel geliştirmede ya da on-prem kurulumda:

Lunixi.configure({
  apiBaseUrl: 'https://api-gateway.lunixi.com/',
  cdnBaseUrl: 'https://cdn.lunixi.com/',
});

Bunu createCardField'dan önce çağırın.

Neden önemli

Kart verisi sizin JavaScript'inizin erişemediği bir origin'de yaşar. Bu, PCI DSS kapsamını daraltır: sayfanızda kart numarası hiç bulunmadığı için o sayfa kart verisi işleyen bir bileşen sayılmaz.

Kendi <input> alanınıza kart numarası aldığınız anda o sayfa PCI kapsamına girer. Hosted field tam olarak bunu engellemek içindir.

Parent'a ne geçer, ne geçmez

Iframe içeriden dışarıya yalnız şunları bildirir:

Mesaj	İçerik
`CARD_VALIDITY_CHANGED`	Yalnız `true` / `false` — alan geçerli mi
`CARD_BRAND_CHANGED`	Tespit edilen marka (`VISA`, `MASTERCARD` …)
`CARD_BIN_CHANGED`	İlk 6 hane — banka tespiti ve taksit tablosu için
`HEIGHT_CHANGED`	Iframe'in piksel yüksekliği (yeniden boyutlandırma)
`TOKENIZATION_STARTED` / `TOKENIZATION_FINISHED`	Tokenizasyonun başladığı/bittiği
`TOKENIZED`	`paymentMethodToken`, `brand`, `last4`, `cardHolderName`, `cardSave`
`ERROR`	`code` — aşağıdaki tabloya bakın

🚫

PAN ve CVC hiçbir mesajda geçmez. Tokenizasyondan sonra elinizde yalnız opak paymentMethodToken ve last4 olur. Kart numarasını parent sayfada okumanız mümkün değildir — tasarım böyle.

BIN'in (ilk 6 hane) dışarı verilmesi bilinçlidir: taksit tablosunu ve banka kampanyasını göstermek için gerekir, tek başına kartı kullanılabilir kılmaz.

Parent'tan iframe'e gönderilenler

INIT · TOKENIZE · FOCUS · RESET · PING

Bunları doğrudan yazmazsınız; SDK'nın metotları arkada bu mesajlara dönüşür.

Tokenizasyon

TOKENIZE geldiğinde iframe kendisi platforma gider:

POST /api/v1/payments/form/tokenize

Yanıttaki cardToken'ı TOKENIZED mesajıyla parent'a iletir. Yani kart verisi iframe → platform yolunu izler, sizin sunucunuzdan geçmez.

Sonra ödemeyi bu token'la tamamlarsınız.

Hata kodları

Kod	Anlamı
`tokenize_not_initialized`	`INIT` gelmeden `TOKENIZE` çağrıldı
`card_invalid`	Alan geçerli değil — kullanıcı henüz tamamlamamış
`tokenize_failed`	Platform tokenizasyonu reddetti
`tokenize_network_error`	Iframe platforma ulaşamadı

Güvenlik kurgusu

Bu alanın koruması birkaç katmandan gelir ve hepsi fail-closed:

Parent origin iframe URL'sinden verilir. Iframe, parent origin'i bilmiyorsa ya da zarf güvenli değilse hiç postMessage yapmaz — sessizce durur.
Katı CSP. default-src 'none', script-src 'self', form-action 'none', object-src 'none', base-uri 'none'; connect-src yalnız platform adresine açık.
frame-ancestors HTTP başlığında zorlanır. Meta etiketinde bilinçli olarak yoktur (orada zaten yok sayılır); asıl kural CDN/nginx tarafında yanıt başlığı olarak uygulanır — yani alanı kimin çerçeveleyebileceği sunucu tarafında sabittir.

⚠️

Alanı kendi sitenizde çerçeveleyebilmeniz için origin'inizin izinli olması gerekir. İzinli değilse iframe yüklenir ama hiçbir mesaj göndermez; boş bir alan görür ve konsolda hata bulamazsınız. İlk entegrasyonda bu belirti origin kaydınızı kontrol etmeniz gerektiği anlamına gelir.

Ne zaman bu, ne zaman tam checkout

İhtiyaç	Seçim
Ödeme ekranının tamamını biz çizelim	Checkout Form
Ekran benim, yalnız kart alanı sizden	Kart Alanı (bu sayfa)
Kart verisine hiç dokunmadan kart saklama	Kart Alanı + `cardSave`

İlgili

Web SDK Genel Bakış — loader, modlar, kimlik doğrulama modelleri
Checkout Form — tam ödeme ekranı
Portal SDK — portalın kart formu aynı akışa devreder

Genel Bakış KYC SDK