Kuveyt Türk POS'un Wix'e Bağlanma Süreci: Güvenli ve Uyumlu Ödeme Sistemi

Katılım Bankacılığına Uygun Ödeme Altyapısı

Kuveyt Türk, Türkiye'nin önde gelen katılım bankalarından biri olarak faizsiz bankacılık prensiplerine uygun hizmetler sunuyor. E-ticaret işletmeleri için bu özellik sadece dini bir tercih meselesi değil, aynı zamanda belirli bir müşteri kitlesine ulaşmanın anahtarı. Bazı müşterileriniz konvansiyonel bankaları tercih etmezken, katılım bankalarıyla çalışmayı öncelik olarak görüyor. Wix'e Kuveyt Türk POS bağladığınızda, her iki grup müşteriye de hitap edebiliyorsunuz.

Bağlantı süreci teknik görünse de aslında mantıklı bir akış izliyor. Önce bankadan aldığınız bilgileri Wix'in güvenli alanına yerleştiriyorsunuz. Sonra ödeme başlatan bir sistem kuruyorsunuz. Müşteri ödeme yaptığında banka doğrulama yapıyor, ardından size sonucu bildiriyor. Siz de bu sonuca göre siparişi işliyorsunuz. Bu döngü her işlemde tekrar ediyor ama sistem otomatik çalıştığı için siz sadece sonuçları görüyorsunuz.

Kuveyt Türk'ün POS sistemi hem tek çekim hem de taksitli ödemeleri destekliyor. Tek çekim işlemlerde müşteri tutarın tamamını bir kerede ödüyor. Taksitli işlemlerde ise tutarı bölüyor, aylık ödemeler yapıyor. Hangi seçeneği sunacağınız size kalmış. Taksit isterseniz komisyon oranları artıyor ama müşteri için alışveriş daha cazip hale geliyor. Yüksek tutarlı ürünlerde taksit şart gibi - kimse 10.000 TL'lik bir ürünü tek çekimle almak istemez.

Banka Tarafından Sağlanan Bağlantı Bilgileri

Kuveyt Türk'e Free POS başvurunuz onaylandığında banka size kritik bilgiler gönderiyor. Bu bilgiler olmadan hiçbir şey yapamıyorsunuz çünkü bunlar sizin dijital kimliğiniz. İlk bilgi Merchant ID - yani mağaza numaranız. Bu numara Kuveyt Türk sisteminde sizin işletmenizi temsil ediyor. Her POS başvurusuna özgü, benzersiz bir ID. Eğer birden fazla web siteniz varsa, her birine ayrı Merchant ID alabilirsiniz.

İkinci önemli bilgi Customer ID - müşteri numaranız. Bu sizin Kuveyt Türk'teki hesap numaranız. Bir müşteri birden fazla Merchant ID'ye sahip olabilir ama Customer ID hep aynı kalır. Banka bu numarayla hesabınızı bulup ödeme gelirlerini yatırıyor.

Üçüncü olarak User Code var - kullanıcı kodunuz. Banka paneline giriş yaparken bu kodu kullanıyorsunuz. Normal panele girmek için bir kod, API istekleri için başka bir kod gerekebiliyor. API kullanıcısını banka panelinde kendiniz oluşturuyorsunuz. "Sanal Pos" menüsünden "Yeni Kullanıcı Ekle" diyorsunuz, rolü "API" seçiyorsunuz. Bu kullanıcının kodunu ve şifresini not ediyorsunuz çünkü bunlar Wix entegrasyonunda kullanılacak.

Son olarak Password ve güvenlik anahtarı bilgileri var. Password, API kullanıcısının şifresi. Güvenlik anahtarı ise hash hesaplamalarında kullanılıyor. Hash, gönderdiğiniz verilerin yolda değiştirilmediğini kanıtlayan bir güvenlik mekanizması. Güvenlik anahtarını kimseyle paylaşmamalısınız - bu anahtar ele geçerse, kötü niyetli kişiler sizin adınıza işlem yapabilir.

Velo Backend'e Bilgilerin Tanımlanması

Bu bilgileri aldıktan sonra Wix tarafına geçiyorsunuz. Wix Editor'ü açıp Dev Mode'u aktifleştirdiğinizde sol tarafta Code Panel çıkıyor. Burada Secrets Manager var - hassas bilgilerinizi sakladığınız güvenli bir kasa gibi. Normal kod dosyalarında şifre yazmak tehlikeli çünkü kod bazen tarayıcıda görünebilir veya yanlışlıkla paylaşılabilir. Secrets Manager'daki bilgiler ise sadece sunucu tarafında kalıyor, hiçbir zaman tarayıcıya gitmiyor.

Secrets Manager'ı açın ve her bilgi için ayrı bir "secret" oluşturun. İsimlendirme önemli - anlamlı ve tutarlı isimler kullanın. Örneğin kuveytturk_customer_id diye bir secret oluşturup içine Customer ID'nizi yazın. Aynı şekilde kuveytturk_merchant_id, kuveytturk_user_code, kuveytturk_password ve kuveytturk_security_key secret'larını ekleyin. Her birinin değerini bankadan aldığınız bilgilerle doldurun.

Backend kodunuzda bu secret'lara erişmek için wix-secrets-backend modülünü kullanıyorsunuz. Örneğin:

import { getSecret } from 'wix-secrets-backend';

const customerId = await getSecret('kuveytturk_customer_id');
const merchantId = await getSecret('kuveytturk_merchant_id');

Bu şekilde bilgiler güvenli bir şekilde kodunuza geliyor. await kelimesi önemli çünkü secret okuma asenkron bir işlem - biraz zaman alıyor. Secret'lar hazır olduktan sonra bunları ödeme başlatma fonksiyonunuzda kullanıyorsunuz.

Backend klasöründe yeni bir dosya oluşturun, adı "kuveytturkService.jsw" olsun. Bu dosya tüm Kuveyt Türk işlemlerini yönetecek. Ödeme başlatma, hash hesaplama, işlem sorgulama gibi fonksiyonlar burada olacak. Dosya hazır olduğunda fonksiyonlarınızı export ederek frontend'den erişilebilir hale getirin.

Ödeme Başlatma ve 3D Doğrulama Yönlendirmesi

Müşteri sitenizde sepetini doldurmuş, ödeme sayfasına gelmiş, kart bilgilerini giriyor. "Ödeme Yap" butonuna bastığında frontend kodunuz devreye giriyor. Kart numarası, son kullanma tarihi, CVV ve kart sahibi adını alıp backend fonksiyonunuza gönderiyorsunuz. Burada dikkat edilmesi gereken bir nokta var: kart bilgilerini asla frontend'de saklamayın veya işlemeyin. Direkt backend'e iletin.

Backend fonksiyonunuz bu bilgileri alıyor ve Kuveyt Türk'ün beklediği formata çeviriyor. İlk olarak sipariş numarası üretiyorsunuz - tarih damgası ve rastgele sayı kombinasyonu güvenli bir yöntem. Bu numara hem sizin sisteminizde hem Kuveyt Türk'te aynı olacak. Tutarı kuruş cinsine çeviriyorsunuz çünkü banka 100 TL yerine "10000" bekliyor.

Şimdi kritik bir adım geliyor: hash hesaplama. Hash, gönderdiğiniz verilerin parmak izi gibi. Belirli parametreleri belirli bir sırayla birleştirip şifreliyorsunuz. Kuveyt Türk için sıralama şöyle: MerchantId, MerchantOrderId, Amount, OkUrl, FailUrl, UserName, SecurityKey. Bu parametreleri "|" işaretiyle ayırıyorsunuz ve HMACSHA1 algoritmasıyla şifreliyorsunuz. Sonuç bir string oluyor, bunu bankanın API'sine gönderiyorsunuz.

Tüm bu bilgileri XML formatında paketliyorsunuz. Kuveyt Türk JSON değil XML kullanıyor. XML mesajınızda APIVersion'ı "TDV2.0.0" olarak belirtmeniz çok önemli - eski versiyonlar desteklenmiyor. Mesajı bankanın endpoint'ine POST ediyorsunuz. Test ortamı için genellikle boatest.kuveytturk.com.tr, canlı ortam için boa.kuveytturk.com.tr.

Banka size bir HTML yanıtı dönüyor. Bu HTML içinde bir form ve JavaScript kodu var. Form otomatik submit oluyor ve müşteriyi Kuveyt Türk'ün 3D Secure ekranına götürüyor. Artık müşteri bankanın kontrolünde. Ekranda işlem detayları görünüyor - ne kadar para çekileceği, hangi mağazadan alışveriş yaptığı, tarih-saat bilgileri.

Banka arka planda risk analizi yapıyor. Müşterinin geçmiş alışveriş davranışı, cihaz bilgileri, IP adresi, işlem tutarı gibi verileri değerlendiriyor. Düşük riskli bulursa SMS şifresi sormadan direkt onaylıyor - buna "sorunsuz doğrulama" deniyor. Yüksek riskli bulursa müşterinin telefonuna bir kod gönderiyor, müşteri kodu giriyor ve işlem tamamlanıyor.

Callback URL ile İşlem Sonucunun Alınması

İşlem tamamlandığında - başarılı veya başarısız fark etmez - banka müşteriyi sizin belirlediğiniz URL'e yönlendiriyor. Bu URL'i ödeme başlatırken OkUrl ve FailUrl parametreleriyle göndermiştiniz. Başarılı işlemler OkUrl'e, başarısız işlemler FailUrl'e dönüyor. Ancak bu yönlendirme müşterinin tarayıcısından geliyor, yani güvenli değil. Müşteri teoride URL'i manipüle edebilir. Bu yüzden callback URL'inizde mutlaka doğrulama yapmalısınız.

Callback URL'i için Wix'in HTTP Functions özelliğini kullanıyorsunuz. "http-functions.js" dosyasında post_kuveytturkCallback adında bir fonksiyon oluşturuyorsunuz. Bu fonksiyon dışarıdan POST istekleri kabul ediyor. Banka size form data olarak birçok parametre gönderiyor. En kritik olanları: ResponseCode (işlem sonucu), MerchantOrderId (sipariş numaranız), HashData (bankanın hash'i), RRN (referans numarası), OrderId (bankanın işlem ID'si).

İlk kontrol hash doğrulaması. Banka hash hesaplarken MerchantOrderId, RRN, ResponseCode, OrderId ve SecurityKey kullanıyor. Siz de aynı parametrelerle hash hesaplayıp bankanın gönderdiği HashData ile karşılaştırıyorsunuz. Eşleşmiyorsa veri manipüle edilmiş olabilir, işlemi reddedin. Eşleşiyorsa ResponseCode'u kontrol edin.

Sadece "00" kodu başarılı işlem demek. Diğer tüm kodlar hata, red veya başarısızlık anlamına geliyor. "00" görüyorsanız müşteri ödemeyi başarıyla tamamlamış, kartından para çekilmiş. Siparişin durumunu "ödendi" olarak güncelleyin, müşteriye onay e-postası gönderin, envanter sistemine bildirim yapın. OrderId ve RRN'i veritabanına kaydedin çünkü ileride iade veya sorgulama için lazım olabilir.

ResponseCode "00" değilse işlem başarısız. Sipariş durumunu "ödeme başarısız" olarak işaretleyin. Hata koduna bakarak müşteriye bilgi verin. "51" yetersiz bakiye anlamına gelir, "54" kartın süresi dolmuş demektir, "05" kart bankası tarafından reddedilmiş. Bu kodları Türkçe mesajlara çevirip müşteriye anlaşılır şekilde gösterin. Müşteri tekrar deneme şansı verebilirsiniz veya alternatif ödeme yöntemleri önerebilirsiniz.

Tek Çekim ve Taksitli İşlemler

Kuveyt Türk POS hem tek çekim hem de taksitli işlemleri destekliyor ama bunlar farklı şekillerde çalışıyor. Tek çekim basit - müşteri tutarın tamamını bir seferde ödüyor. XML mesajınızda InstallmentCount parametresini "0" veya "1" olarak gönderiyorsunuz. Komisyon oranı düşük, işlem hızlı, müşteri tek bir ödeme yapıyor.

Taksitli işlemlerde InstallmentCount parametresine 2, 3, 6, 9, 12 gibi değerler veriyorsunuz. Ancak dikkat: taksit yapmak için bankanızla taksit anlaşması yapmanız gerekiyor. Free POS başvurusu yaparken veya sonrasında banka şubesine gidip "taksit açmak istiyorum" demeniz lazım. Banka size hangi taksit sayılarını sunabileceğinizi ve komisyon oranlarını söylüyor.

Taksitli işlemlerde komisyon oranları artıyor. Tek çekim %1 ise, 3 taksit %1.5, 6 taksit %2, 9 taksit %2.5 olabilir. Bu oranları müşterinize yansıtabilir veya kendiniz üstlenebilirsiniz. Eğer yansıtırsanız, müşteri 100 TL'lik ürünü 3 taksitle alırken toplam 101.5 TL öder - her ay yaklaşık 33.83 TL. Yansıtmazsanız müşteri 100 TL öder ama siz 98.5 TL alırsınız çünkü %1.5 komisyon sizden kesilir.

Frontend'de taksit seçeneklerini dinamik olarak gösterebilirsiniz. Tutar arttıkça daha fazla taksit seçeneği sunabilirsiniz. Örneğin 100 TL'nin altında sadece tek çekim, 100-500 TL arası 3 taksit, 500-1000 TL arası 6 taksit, 1000 TL üzeri 9 veya 12 taksit. Bu müşteri deneyimini iyileştiriyor çünkü küçük tutarlarda gereksiz taksit seçenekleri göstermiyorsunuz.

Taksit tablosu gösterirken aylık ödeme tutarını hesaplayıp gösterin. "9 taksit" demek müşteriye pek bir şey ifade etmiyor ama "9 ay x 111.11 TL" daha anlamlı. Müşteri bütçesini planlayabiliyor, aylık ne kadar ödeyeceğini biliyor. Toplam tutarı da gösterin - bazen taksitle alışveriş tek çekimden daha pahalıya mal olabiliyor, müşteri bunu bilmeli.

Bağlantının Doğruluğu ve Süreklilik

Bağlantı kurulduktan sonra sistemin düzgün çalıştığından emin olmanız gerekiyor. İlk hafta her gün kontrol yapın - işlemler başarıyla tamamlanıyor mu, callback düzgün çalışıyor mu, siparişler doğru güncelleniyor mu. Bir sorun varsa erken tespit edip çözün. Müşteri ödeme yapamadığında hemen başka siteye gider, o satışı kaybedersiniz.

Logları mutlaka tutun. Her ödeme başlatma, her hash hesaplama, her callback'i kaydedin. Bir sorun olduğunda loglar olmadan hata bulmak çok zor. Hangi parametreyi yanlış gönderdiğinizi, hash'in nerede uyuşmadığını, bankanın ne döndürdüğünü görebilmeniz lazım. Wix'in console.log fonksiyonunu kullanabilir veya ayrı bir log tablosu oluşturabilirsiniz.

Secrets Manager'daki bilgileri düzenli güncelleyin. Özellikle güvenlik anahtarını 6 ayda bir değiştirmek iyi bir güvenlik pratiği. Değiştirdiğinizde Wix'teki secret'ı da güncellemeyi unutmayın. Kuveyt Türk'ten gelen güncelleme e-postalarını takip edin - bazen API'de değişiklikler oluyor, yeni parametreler ekleniyor veya eski versiyonlar kapatılıyor.

Banka paneli ve Wix panelini düzenli karşılaştırın. Sabah Kuveyt Türk paneline girip gece gelen ödemeleri görün, ardından Wix panelinde bu siparişlerin doğru işlendiğini teyit edin. Tutarlar uyuşuyor mu? Sipariş sayıları eşleşiyor mu? Bir uyumsuzluk varsa hemen araştırın. Bazen callback başarısız olabilir, bazen müşteri ödemeyi yarıda bırakabilir - bu durumları tespit edip yönetmeniz gerekiyor.

Kuveyt Türk POS'un Wix'e bağlanması, doğru yapılandırıldığında sorunsuz çalışan güvenli bir sistem. Banka bilgilerinizi Velo backend'e tanımlayın, ödeme akışını doğru kurun, callback'i iyi yapılandırın. Sistem otomatik çalıştığında hem tek çekim hem taksitli işlemleri destekleyecek. Katılım bankacılığına uygun, müşteri güvenini kazanan bir ödeme altyapısına sahip olacaksınız.