Skip to main content
Kart Elementleri, kendi tasarladığınız ödeme formuna güvenli bir kart girişi alanı yerleştirmenizi sağlar. Hassas kart bilgileri Tahsilat’ın PCI-DSS uyumlu iframe’i içinde kalır, hiçbir zaman sizin sunucularınızdan geçmez.
Kart Elementleri ile ödeme formunun tamamını siz tasarlarsınız. Tahsilat.com sadece kart numarası, son kullanma tarihi ve CVV alanlarını güvenli bir iframe olarak sağlar. Taksit, bin sorgulama gibi işlemleri sizin yerinize otomatik yapar.

Kurulum ve Kart Elementini Oluşturma

Kart elementi, verdiğiniz kutunun (#card-element) içini tamamen doldurur; kutunun yüksekliğini siz belirlersiniz (en az 44px). Kutuyu kendi sarmalayıcı div’inizin içine koyun; SDK hata mesajını bu sarmalayıcının hemen altına yazar (bkz. Hata mesajlarının gösterimi).

Kart Elementi Oluşturma

Kart elementi, güvenli kart bilgisi toplama alanını sayfanıza yerleştirir. Temel kullanımda sadece tutar ve para birimi yeterlidir. Taksit, stil, placeholder gibi ek özellikler için aşağıdaki bölümlere bakınız.
amount kuruş cinsindendir. 100,00 TL için 10000 olarak girilmelidir. currency belirtilmezse varsayılan TRY kullanılır.

Ödeme Başlatma

Kart bilgileri girildikten sonra confirmPayment metodu ile ödeme başlatılır. Aşağıda farklı senaryolar için örnekler bulunmaktadır.

1. Müşteri Bilgileri ile Ödeme

Ödeme isteği oluşturulurken customer_id gönderilmemesi durumunda her ödeme için müşteri bilgileri tekrar alınır ve yeni bir müşteri oluşturulur. Bu durumda müşteri takibi ve raporlama süreci zorlaşabilir.Üye işyeri arayüzünden ya da Müşteriler sayfasından api aracılığı ile müşteri oluşturarak customer_id parametresini kullanabilirsiniz.

2. Müşteri ID ile Ödeme

Mevcut bir müşteriyi customer_id ile ilişkilendirdiğinizde müşteri bilgileri zorunlu değildir. Müşteri, public key ile oluşturulamaz; sadece secret key ile oluşturulabilir ve JS SDK bunu desteklemez. Bunun için Müşteriler sayfasını kontrol ediniz.

3. Ürün ID’leri ile Ödeme

Önceden oluşturulmuş ürün ID’lerini kullanarak ödeme başlatabilirsiniz. Ürün, public key ile oluşturulamaz; sadece secret key ile oluşturulabilir ve JS SDK bunu desteklemez. Bunun için Ürünler sayfasını kontrol ediniz.

Abonelik Ürünleri

Abonelik ürünü içeren ödemede kart elementi, müşterinin tekrarlayan tahsilat izni vereceğini belirten metni kart alanının altında otomatik gösterir. Ürünleri elementi oluştururken verin, metin element yüklenince kendiliğinden görünsün:
Ürünler sonradan belli oluyorsa cardElement.setProductIds([...]) kullanın. Ürünleri yalnız confirmPayment() içinde verirseniz ilk çağrı metni gösterir ve subscription_mandate_required koduyla reddedilir; müşteri metni gördükten sonra ikinci çağrı ödemeyi başlatır. Metin henüz yüklenmeden yapılan çağrı da aynı kodla reddedilir. Bu ret yalnız Promise ile döner, paymentError event’i tetiklenmez; bu yüzden catch ile yakalayın. Metin alınamazsa çağrı subscription_mandate_failed koduyla reddedilir.

4. Ürün Bilgileri İle Ödeme

5. Müşteri ile İlişkilendirilmiş Ödeme

Mevcut bir müşteriyi ödeme ile ilişkilendirmek için customer_id parametresini kullanabilirsiniz. Bu durumda ödeme esnasında müşteri bilgileri tekrardan alınmaz: Müşteri oluşturmak için Müşteriler sayfasını ziyaret edebilirsiniz.

Ödeme Sonucunu Alma

confirmPayment() bir Promise döner: ödeme başarıyla tamamlanınca çözülür, diğer her durumda reddedilir. 3D Secure gerekiyorsa SDK doğrulama penceresini kendisi açar, kapatır ve Promise ancak sonuç kesinleşince biter. Aynı sonuçlar SDK event’leri ile de yayınlanır; ikisinden birini kullanmanız yeterlidir.
Reddedilen her Promise bir hatadır, “bekleyen ödeme” değildir. Bekleyen durum yalnızca paymentProcessing event’i ile bildirilir. Ret aldığınızda err.message değerini müşteriye gösterin ve ödeme düğmesini yeniden açın; sonuç sorgulama döngüsüne girmeyin.
Eğer ödemeyi pre_auth: true ile başlattıysanız, sonuç aldığınızda is_pre_auth değerini kontrol edin. true dönmesi durumunda ödeme başarılıdır ancak tutar karttan çekilmemiş, yalnızca bloke edilmiştir. Bloke edilen tutarı çekmek için ayrıca ön provizyonu kapatma işlemi yapmanız gerekmektedir.

Başarılı Sonuç Alanları

Ret (catch) Alanları

confirmPayment() aynı anda yalnızca bir kez çağrılabilir. Önceki çağrı bitmeden yenisini yaparsanız code: "payment_in_progress" ile reddedilir; bu yüzden düğmeyi tıklanır tıklanmaz pasifleştirin, Promise bitince yeniden açın.

Sonucu Doğru İşleme

Entegrasyonunuzu canlıya almadan önce aşağıdaki maddeleri kontrol edin. Bunlardan biri eksikse müşteri, ödemesi reddedildiği hâlde ekranda “ödeme kontrol ediliyor” gibi bir bekleme mesajında kalabilir.
  1. Başarı ve ret sonuçlarını ayrı işleyin. paymentSuccess ile paymentError event’lerini (veya Promise’in then ve catch dallarını) aynı fonksiyona bağlamayın. Ret sonucunu bir başarı adayı gibi ele alıp beklemeye almak en sık yapılan hatadır.
  2. Ret kesin bir sonuçtur; müşterinin tekrar denemesine izin verin. paymentError geldiğinde karttan tahsilat yapılmamıştır. message alanını müşteriye gösterin ve ödeme düğmesini yeniden açın; müşteri aynı veya başka bir kartla tekrar deneyebilir. Ödeme düğmesini kalıcı olarak kapatmayın.
  3. Sunucu tarafı doğrulamanız başarısız sonuçları da kesin saymalı. Siparişi webhook ya da işlem sorgulama ile doğruluyorsanız yalnızca başarıyı değil, başarısızlığı da işleyin:
  4. Webhook’ta başarısız olaylara da abone olun. Üye işyeri panelindeki webhook ayarlarında yalnızca Başarılı olayını seçerseniz reddedilen ödemeler için bildirim almazsınız. Başarısız ve Şüpheli İşlem olaylarını da seçin. Ayrıntılar için Webhook Yönetimi sayfasına bakın.

3D Secure Doğrulaması

Banka 3D Secure istediğinde SDK, sayfanızın üstünde bir doğrulama penceresi açar; müşteri bankasının sayfasında SMS şifresini girer, sonuç gelince pencere kendiliğinden kapanır ve Promise sonuçlanır. Sizin bir yönlendirme veya pencere yönetimi yapmanız gerekmez.
  • Pencere tarayıcının en üst katmanında açılır; sayfanızdaki <dialog>, modal veya yüksek z-index değerli öğeler onu örtmez. Kendi modalınızı açık tutabilirsiniz.
  • Ödeme banka adımına gitmeden reddedilirse (örneğin SmartCheck engeli) pencere açılır açılmaz kapanır; sebep catch bloğundaki message alanındadır.
  • Müşteri pencereyi kapatmak isterse onay sorulur; onaylarsa Promise type: "cancelled" ile reddedilir.
  • Pencere en fazla 15 dakika açık kalır; süre dolarsa code: "overlay_timeout" ile reddedilir.
  • Banka sonucu gecikirse paymentProcessing event’i bir kez tetiklenir ve pencere sonucu beklemeye devam eder.

Hata Mesajlarının Gösterimi

Kart alanlarıyla ilgili her hata (geçersiz numara, geçmiş tarih, eksik CVV ve ödeme isteği sırasında sunucunun kart alanları için döndürdüğü doğrulama hataları) elementin içinde ilgili alanı kırmızıya çevirir ve change event’inde state.error olarak gelir. Varsayılan olarak SDK bu mesajı sizin yerinize de gösterir: kart kutunuzun hemen altına kırmızı, 12px bir satır ekler. Kutu tek başına bir sarmalayıcı div içindeyse satır sarmalayıcının altına eklenir; böylece sabit yükseklikli kutular taşmaz. Mesajı kendi tasarımınızla göstermek istiyorsanız hideErrors: true verin ve state.error değerini kendiniz yazın:
Canlı anahtarla (pk_live_) kart numarası tamamlanır tamamlanmaz sağlama (Luhn) kontrolü yapılır; hatalı numara ödeme isteği gönderilmeden yakalanır. Sandbox’ta test kartları bu kontrolden muaftır.

Taksit

Kullanıcı kart numarasının ilk 6-8 hanesini girdiğinde SDK otomatik olarak BIN sorgulaması yapar ve taksit seçeneklerini döner. Bu seçenekleri kendi UI’ınızda göstermeniz gerekir.
Taksit seçeneklerindeki installment değeri şifrelenmiş bir değerdir. Bu değeri olduğu gibi installment_count parametresine geçmelisiniz. Düz sayı (1, 2, 3…) göndermeyiniz.

Taksit Akışı

  1. Kullanıcı kart numarasını girer
  2. SDK otomatik BIN lookup yapar
  3. installments eventi tetiklenir
  4. Siz taksit seçeneklerini gösterirsiniz
  5. Seçilen taksitin şifreli installment değerini installment_count olarak göndermelisiniz.

Tam Örnek

Aşağıda taksit seçimi dahil uçtan uca bir ödeme akışı gösterilmektedir. Bu örneği kendi projenize uygun şekilde özelleştirebilirsiniz.

Installments Event Verisi

Özelleştirme

Ödeme parametrelerini önceden tanımlayarak confirmPayment() çağrısını basitleştirebilirsiniz:

Event’ler

Kart elementi event’leri (cardElement.on)

SDK event’leri (tahsilat.on)

Kart alanı eksik veya geçersizken (incomplete_card) ya da sunucu alan bazlı doğrulama hatası döndüğünde paymentError tetiklenmez; bu durumlar yalnızca Promise reddi ve state.error ile bildirilir, çünkü ödeme henüz başlamamıştır.

confirmPayment() Parametreleri

elements.create() Parametreleri

Ödeme tutarı ile ürünlerin toplam tutarı eşleşmelidir. Aksi takdirde ödeme reddedilir.
Ödeme sonuçlarını almak için confirmPayment promise sonucunu dinleyebilir veya backend tarafında webhook entegrasyonu yapabilirsiniz. Webhook en güvenilir yöntemdir.