Wix'e Kuveyt Türk Sanal POS Kurulum Rehberi: Adım Adım Süreç

Kurulum Öncesi Hazırlık: Bankadan Gelen Bilgiler

Kuveyt Türk'ten Free POS başvurunuz onaylandığında size bir e-posta geliyor. Bu e-postada işinize yarayacak kritik bilgiler var ve bunları dikkatle saklamanız gerekiyor. İlk olarak Müşteri Numarası var - bu sizin Kuveyt Türk'teki hesap kimliğiniz. İkinci önemli bilgi Mağaza Numarası, yani sanal POS terminalinizin ID'si. Üçüncü olarak Kullanıcı Adı ve Şifre geliyor, bunlarla banka paneline giriş yapacaksınız.

Bu bilgileri aldıktan sonra ilk yapmanız gereken şey, kurumsal panele giriş yapmak. Tarayıcınızda https://kurumsal.kuveytturk.com.tr adresine gidin. Müşteri numaranızı, kullanıcı adınızı ve şifrenizi girin. Giriş yaptığınızda telefonunuza bir SMS şifresi gelecek, onu da ekrana girip onaylayın. Artık banka panelindesiniz.

Panelde ilk göreviniz bir API kullanıcısı oluşturmak. Normal kullanıcı bilgileriniz web paneli için, API kullanıcısı ise programatik erişim için. "Tüm İşlemler" menüsünden "Sanal Pos" seçeneğine tıklayın, ardından "Yeni Kullanıcı Ekle" butonuna basın. Açılan ekranda kullanıcı adı belirleyin - Türkçe karakter ve boşluk kullanmayın, sadece İngilizce harfler ve rakamlar. E-posta, GSM ve TC numaranızı girin. En önemli kısım: "Kullanıcı Rolü" bölümünde mutlaka "API" seçin. Normal rol seçerseniz sistem isteklerinizi reddeder.

Şifre belirlerken dikkatli olun - en az 8 karakter, içinde büyük harf, küçük harf ve rakam bulunmalı. Bu şifreyi not edin çünkü bir daha göremeyeceksiniz. "Durum" kısmını "Aktif" olarak bırakın ve kaydedin. Artık elinizde iki set bilgi var: normal kullanıcı bilgileri (panel girişi için) ve API kullanıcı bilgileri (Wix entegrasyonu için).

Wix Velo Backend Yapılandırması

Şimdi Wix tarafına geçelim. Wix Editor'ünüzü açın ve sol üst köşedeki "Dev Mode" butonuna tıklayın. Bu, geliştirici araçlarını aktifleştiriyor. Biraz bekleyin, sol tarafta "Code Panel" açılacak. Burada Velo backend dosyalarınızı göreceksiniz.

İlk adım Secrets Manager'a girmek. Code Panel'de üstte "Secrets Manager" seçeneği var, tıklayın. Burası hassas bilgilerinizi güvenli şekilde saklamanızı sağlayan bir kasa gibi. Şimdi Kuveyt Türk'ten aldığınız bilgileri buraya ekleyeceğiz. "Add Secret" butonuna basın ve şu bilgileri tek tek ekleyin:

kuveytturk_customer_id adında bir secret oluşturun, içine müşteri numaranızı yazın. kuveytturk_merchant_id için mağaza numaranızı girin. kuveytturk_api_username için API kullanıcı adınızı yazın. kuveytturk_api_password için API şifrenizi girin. Son olarak kuveytturk_hash_password ekleyin - bu genellikle API şifrenizle aynı oluyor ama bazı durumlarda farklı olabiliyor, banka size özel belirtmişse onu kullanın.

Bu bilgileri neden doğrudan koda yazmıyoruz? Çünkü kod bazen tarayıcıda görünebilir, yanlışlıkla paylaşılabilir veya versiyonlama sistemine yüklenebilir. Secrets Manager'daki bilgiler ise sadece sunucu tarafında kullanılır, hiçbir zaman tarayıcıya gönderilmez. Bu güvenliğin temel kuralı.

Secrets'ları ekledikten sonra, backend klasöründe yeni bir dosya oluşturun. Dosya adı "kuveytturkService.jsw" olsun. Backend dosyaları ".jsw" uzantısıyla biter - "w" harfi "web" anlamına geliyor. Bu dosyaya tıklayın ve kod editörü açılacak.

Ödeme Başlatma Endpoint'inin Oluşturulması

Backend dosyanızda ilk olarak gerekli modülleri import edin. wix-secrets-backend modülünden secret'larınızı okuyacaksınız, wix-fetch ile bankanın API'sine istek göndereceksiniz, crypto modülüyle hash hesaplayacaksınız. İmport satırlarınız şöyle olmalı:

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

Şimdi ödeme başlatma fonksiyonunu yazalım. Bu fonksiyon frontend'den kart bilgilerini alacak, hash hesaplayacak, bankanın API'sine istek gönderecek ve 3D Secure yönlendirme URL'ini döndürecek. Fonksiyonun başına export kelimesini eklemeyi unutmayın, yoksa frontend'den erişemezsiniz.

Fonksiyon içinde önce secret'ları okuyun. Ardından sipariş için benzersiz bir numara üretin - tarih damgası ve rastgele sayı kombinasyonu iyi bir yöntem. Tutarı kuruş cinsine çevirin - Kuveyt Türk 100 TL için "10000" bekliyor. Hash hesaplama zamanı geldi - parametreleri doğru sırayla birleştirip HMACSHA1 ile şifreleyin: MerchantId, MerchantOrderId, Amount, OkUrl, FailUrl, UserName, hashPassword.

Callback URL'lerinizi belirleyin. Başarılı işlemler için OkUrl, başarısız işlemler için FailUrl. Bu URL'ler mutlaka https ile başlamalı ve internetten erişilebilir olmalı. Wix sitenizin gerçek URL'ini kullanın. Örneğin: https://yoursite.wixsite.com/mysite/_functions/kuveytturkCallback.

Tüm bu bilgileri XML formatında hazırlayın. Kuveyt Türk JSON değil, XML kullanıyor. XML mesajınızda APIVersion'ı "TDV2.0.0" olarak gönderin - bu çok önemli, eski versiyonlar artık desteklenmiyor. CardType'ı kart numarasının ilk hanelerine bakarak belirleyin: 4 ile başlıyorsa Visa, 5 ile başlıyorsa MasterCard, 9792 ile başlıyorsa Troy.

XML'i hazırladıktan sonra, bankanın API endpoint'ine POST isteği gönderin. Test ortamı için URL genellikle boatest.kuveytturk.com.tr altında, canlı ortam için boa.kuveytturk.com.tr altında. İstek başlıkları önemli: Content-Type "application/xml" olmalı. Yanıtı bekleyin - banka size bir HTML sayfası dönecek. Bu HTML içinde otomatik submit olan bir form var, müşteriyi 3D Secure ekranına yönlendiriyor.

3D Secure Yönlendirme ve Kullanıcı Deneyimi

Backend fonksiyonunuz HTML yanıtını frontend'e döndürüyor. Frontend kodunuz bu HTML'i alıp sayfaya yerleştiriyor. HTML içindeki JavaScript kodu otomatik çalışıyor ve müşteriyi Kuveyt Türk'ün 3D Secure ekranına götürüyor. Bu geçiş saniyeler içinde oluyor, müşteri neredeyse fark etmiyor.

Artık müşteri bankanın kendi sayfasında. Bu sayfa sizin kontrolünüzde değil, tamamen Kuveyt Türk yönetiyor. Ekranda işlem detayları görünüyor - tutar, mağaza adı, tarih-saat. Banka arka planda risk analizi yapıyor: müşterinin alışveriş geçmişi, cihaz bilgileri, IP adresi, işlem tutarı gibi verileri değerlendiriyor.

Eğer sistem düşük riskli bulursa, SMS şifresi sormadan direkt onaylıyor. Buna "frictionless authentication" deniyor - sürtünmesiz doğrulama. Müşteri hiçbir şey yapmadan işlem tamamlanıyor. Yüksek riskli bulursa, müşterinin telefonuna SMS gönderiliyor. Müşteri kodu giriyor, "Onayla" butonuna basıyor.

Onay veya red fark etmeksizin, banka müşteriyi sizin belirlediğiniz callback URL'ine yönlendiriyor. Başarılı işlemler OkUrl'e, başarısız işlemler FailUrl'e gidiyor. Ancak dikkat: bu yönlendirme müşterinin tarayıcısından geliyor, yani teoride manipüle edilebilir. Bu yüzden callback URL'inizde mutlaka doğrulama yapmalısınız.

Callback URL ve İşlem Doğrulaması

Callback URL'i için HTTP Functions kullanmanız gerekiyor. Backend klasöründe değil, "HTTP Functions" klasöründe yeni bir dosya oluşturun. Dosya adı "http-functions.js" olsun - dikkat edin, .jsw değil, .js uzantısı. Bu dosyada dışarıdan POST istekleri kabul edebilirsiniz.

Fonksiyon adını post_kuveytturkCallback olarak belirleyin. Önünde "post_" olması önemli, bu HTTP POST metodu için handler olduğunu gösteriyor. Fonksiyon parametre olarak request alıyor. Request içindeki form verilerine request.formData() ile erişiyorsunuz.

Banka size birçok parametre gönderiyor. En önemlileri: ResponseCode (işlem sonucu), MerchantOrderId (sizin sipariş numaranız), HashData (bankanın hash'i), RRN (referans numarası), OrderId (bankanın işlem ID'si), AuthCode (onay kodu). Bu parametreleri form data'dan alın.

İlk kontrol hash doğrulaması. Banka hash hesaplarken şu parametreleri kullanıyor: MerchantOrderId, RRN, ResponseCode, OrderId, hashPassword. Siz de aynı parametrelerle hash hesaplayın ve bankanın gönderdiği HashData ile karşılaştırın. Eşleşmiyorsa, veri yolda değiştirilmiş olabilir - işlemi reddedin.

Hash doğruysa, ResponseCode'u kontrol edin. Sadece "00" kodu başarılı işlem anlamına geliyor. Diğer tüm kodlar hata veya red. "00" görüyorsanız, sipariş durumunu "ödendi" olarak güncelleyin. OrderId ve AuthCode bilgilerini veritabanına kaydedin - ileride iade veya iptal için lazım olabilir.

ResponseCode "00" değilse, sipariş durumunu "başarısız" olarak işaretleyin. Hata kodunu da kaydedin - müşteriye bilgi vermek veya sorun giderme için kullanabilirsiniz. Bazı yaygın kodlar: "05" kart reddedildi, "51" yetersiz bakiye, "54" kartın süresi dolmuş.

Çift Panel Takip Sistemi ve Avantajları

Kurulum tamamlandıktan sonra artık iki farklı panelden işlemlerinizi takip edebilirsiniz. Bu sistem hem güvenlik hem kontrol açısından büyük avantaj sağlıyor.

Wix Dashboard'unuzda siparişlerin genel durumunu görüyorsunuz. Hangi müşteri ne aldı, sipariş numarası ne, ödeme durumu ne - bunlar Wix panelinde. Eğer Wix Data kullanıyorsanız, "Orders" koleksiyonunuzda tüm detaylar var. Müşteri e-postası, teslimat adresi, ürün bilgileri, ödeme tarihi gibi e-ticaret odaklı bilgiler burada duruyor. Sipariş durumunu "hazırlanıyor", "kargoda", "teslim edildi" şeklinde güncelleyebiliyorsunuz.

Kuveyt Türk Kurumsal Panel'de ise finansal detaylar var. Hangi kartla ödeme yapıldı, kart son 4 hanesi ne, taksit sayısı kaç, komisyon ne kadar kesildi, işlem tam olarak saat kaçta gerçekleşti - bunları banka panelinde görüyorsunuz. Ayrıca gün sonu mutabakatı, haftalık-aylık raporlar, iade işlemleri burada yönetiliyor.

Bu iki panel birbirini tamamlıyor. Örneğin bir müşteri "ödeme yaptım ama sipariş gelmiş görünmüyor" diye şikayet ettiğinde, önce Wix paneline bakıyorsunuz - gerçekten sipariş yok mu? Sonra Kuveyt Türk paneline geçiyorsunuz - ödeme gerçekten gelmiş mi? Eğer ödeme gelmişse ama Wix'te sipariş yoksa, callback sürecinde bir hata olmuş demektir. Logları kontrol edip sorunu çözüyorsunuz.

Tam tersi de olabilir. Wix'te sipariş var ama Kuveyt Türk'te işlem görünmüyor. Bu durumda muhtemelen test işlemi yapılmış veya ödeme başlatma aşamasında hata oluşmuş. Sipariş durumunu "ödeme bekliyor" olarak bırakıp müşteriye tekrar deneme linki gönderebilirsiniz.

Günlük rutin olarak sabah her iki paneli de kontrol etmek iyi bir alışkanlık. Kuveyt Türk panelinde gece gelen ödemeleri görüyorsunuz, Wix panelinde bu siparişlerin doğru işlendiğini teyit ediyorsunuz. Öğleden sonra kargo süreçlerini Wix'ten takip ediyorsunuz. Hafta sonu veya ay sonunda Kuveyt Türk'ten finansal raporları indiriyorsunuz - ne kadar ciro yaptınız, hangi günler daha yoğundu, ortalama sepet tutarı ne gibi analizler yapabilirsiniz.

Test Süreci ve Canlıya Geçiş

Kurulumu tamamladıktan sonra mutlaka test yapın. Kuveyt Türk test kartları sağlıyor - gerçek para çekilmeden tüm akışı deneyebilirsiniz. Test ortamı URL'lerini kullanın, canlı ortam URL'lerini değil. Test kartıyla bir ödeme başlatın. Kart bilgilerini girin, 3D Secure ekranına yönlendirildiğinizi görün, SMS şifresi yerine test kodunu girin.

Callback'in çalıştığını kontrol edin. Wix'te sipariş oluştu mu? Durumu "ödendi" olarak güncellenmiş mi? Kuveyt Türk test panelinde işlem görünüyor mu? Her adımı tek tek doğrulayın. Başarısız işlemleri de test edin - yanlış CVV girin, süresi dolmuş kart numarası kullanın. Sistemin hataları doğru yakaladığını, müşteriye anlamlı mesajlar gösterdiğini teyit edin.

Hash hesaplamalarınızı iki kez kontrol edin. Hash hatası en yaygın sorunlardan biri. Parametrelerin sırası doğru mu? Tüm değerleri string olarak mı gönderiyorsunuz? Pipe karakteri (|) ayırıcı olarak kullanıyor musunuz? Bir hata varsa, banka "Şifrelenen veriler (Hashdata) uyuşmamaktadır" dönüyor.

Test başarılıysa canlıya geçme zamanı. Kuveyt Türk panelinde test modunu kapatın, canlı moda geçirin. Backend kodunuzda API URL'lerini test ortamından canlı ortama değiştirin. Wix sitenizi publish edin. İlk gerçek işleminizi 1 TL gibi küçük bir tutarla yapın. Başarılı olursa, tebrikler - sisteminiz çalışıyor!

Canlıda da logları takip edin. İlk hafta özellikle dikkatli olun. Her işlem sonrası hem Wix hem Kuveyt Türk panellerini kontrol edin. Bir sorun görürseniz, hemen müdahale edin. Müşteri memnuniyeti kritik - ödeme yapamayan müşteri başka siteye gidebilir.

Düzenli bakım yapın. Kuveyt Türk'ten gelen güncelleme e-postalarını okuyun. Bazen API'de değişiklikler oluyor, yeni parametreler ekleniyor veya eski versiyonlar kapatılıyor. Bu güncellemeleri takip edip sisteminizi zamanında güncelleyin. Secrets Manager'daki şifrelerinizi 6 ayda bir değiştirin - güvenlik için iyi bir pratik.

Kuveyt Türk Sanal POS'u Wix'e kurmak, doğru adımları takip ettiğinizde karmaşık değil. API bilgilerini düzgün hazırlayın, Velo backend'de güvenli şekilde saklayın, hash hesaplamalarını doğru yapın, callback'i iyi yapılandırın. Kurulum tamamlandığında katılım bankacılığına uygun, güvenli ve şeffaf bir ödeme sisteminiz olacak. İşlemlerinizi iki panelden de takip ederek hem müşteri memnuniyetini hem finansal kontrolü sağlayabilirsiniz.