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 sonraconfirmPayment metodu ile ödeme başlatılır. Aşağıda farklı senaryolar için örnekler bulunmaktadır.
1. Müşteri Bilgileri ile Ödeme
2. Müşteri ID ile Ödeme
Mevcut bir müşteriyicustomer_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: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çincustomer_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.
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.-
Başarı ve ret sonuçlarını ayrı işleyin.
paymentSuccessilepaymentErrorevent’lerini (veya Promise’inthenvecatchdalları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. -
Ret kesin bir sonuçtur; müşterinin tekrar denemesine izin verin.
paymentErrorgeldiğinde karttan tahsilat yapılmamıştır.messagealanı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. -
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:
- 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üksekz-indexdeğ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
catchbloğundakimessagealanı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
paymentProcessingevent’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 vechange 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 Akışı
- Kullanıcı kart numarasını girer
- SDK otomatik BIN lookup yapar
installmentseventi tetiklenir- Siz taksit seçeneklerini gösterirsiniz
- Seçilen taksitin şifreli
installmentdeğeriniinstallment_countolarak 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ımlayarakconfirmPayment() ç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.