DenizBank POS'un Wix'e Bağlanma Süreci: Hızlı ve Güvenli Entegrasyon

API Bilgilerinin Velo Backend'e İşlenmesi

DenizBank'tan Sanal POS başvurunuz onaylandığında size özel bilgiler geliyor. Bu bilgiler olmadan hiçbir şey çalışmaz çünkü bunlar sizin sistemle DenizBank arasındaki iletişim köprüsü. İlk bilgi Merchant ID - yani işyeri numaranız. DenizBank bu numarayla sizi tanıyor, hangi hesaba para yatıracağını biliyor. Her işletmenin benzersiz bir Merchant ID'si var.

İkinci önemli bilgi Store Key veya bazı kaynaklarda "Shop Code" olarak geçen mağaza anahtarı. Bu anahtar ödeme başlatırken kullanılıyor. Üçüncü bilgi Terminal ID - eğer birden fazla satış kanalınız varsa (web sitesi, mobil uygulama, telefon satış) her birinin ayrı terminal ID'si olabiliyor. Tek bir satış kanalınız varsa genellikle tek terminal kullanırsınız.

Son olarak güvenlik anahtarları var. Bunlardan en önemlisi 3D Secure anahtarı veya "3dpass" olarak adlandırılan parametre. Bu anahtar 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şmayın - bu bilgi ele geçerse sisteminiz tehlikeye girer.

Bu bilgileri aldıktan sonra Wix tarafına geçiyorsunuz. Wix Editor'de Dev Mode'u açın, Code Panel'de Secrets Manager'ı bulun. Burası hassas bilgilerinizi sakladığınız dijital kasa. Her bilgi için ayrı bir "secret" oluşturun. İsimlendirme tutarlı olsun: denizbank_merchant_id, denizbank_store_key, denizbank_terminal_id, denizbank_3d_pass gibi. Değerleri bankadan aldığınız bilgilerle doldurun.

Backend klasöründe yeni bir dosya oluşturun, adı "denizbankService.jsw" olsun. Bu dosya tüm DenizBank işlemlerini yönetecek. Secret'ları okumak için wix-secrets-backend modülünü import edin:

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

const merchantId = await getSecret('denizbank_merchant_id');
const storeKey = await getSecret('denizbank_store_key');

Bu şekilde bilgiler güvenli kalıyor, hiçbir zaman tarayıcıya gitmiyor, sadece sunucu tarafında kullanılıyor.

Ödeme Başlatma ve 3D Secure Yönlendirmesi

Müşteri sitenizde alışverişini tamamladı, "Ödeme Yap" butonuna tıkladı. Frontend kodunuz kart bilgilerini topluyor - kart numarası, son kullanma tarihi, CVV ve kart sahibi adı. Bu bilgileri backend'e gönderiyorsunuz. Backend'de sipariş numarası üretiyorsunuz - tarih damgası ve rastgele sayı kombinasyonu güvenli bir yöntem.

Şimdi kritik bir adım: hash hesaplama. DenizBank için hash parametreleri şu sırada birleştiriliyor: ShopCode, OrderId, Amount, OkUrl, FailUrl, TxnType, InstallmentCount, Rnd, MerchantPass. Rnd rastgele bir değer - genellikle tarih damgası kullanılır. Bu parametreleri yan yana yazıyorsunuz, sonuna MerchantPass ekliyorsunuz, ardından SHA-1 ile şifreliyorsunuz ve Base64 encode ediyorsunuz.

Hash hesapladıktan sonra tüm bilgileri form data olarak paketliyorsunuz. DenizBank'ın endpoint'i genellikle şöyle: test ortamı için https://sanaltest.denizbank.com/mpi/Default.aspx, canlı ortam için https://spos.denizbank.com/mpi/Default.aspx. Form data'yı POST ediyorsunuz. Banka size bir HTML yanıtı dönüyor - bu HTML içinde otomatik submit olan bir form var.

Frontend'iniz bu HTML'i alıp sayfaya yerleştiriyor. Form otomatik çalışıp müşteriyi DenizBank'ı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 ödeyecek, hangi mağazadan alışveriş yaptı. Banka arka planda risk analizi yapıyor - müşterinin alışveriş geçmişi, IP adresi, cihaz bilgileri kontrol ediliyor.

Düşük riskli bulursa SMS şifresi sormadan onaylıyor. Yüksek riskli bulursa müşterinin telefonuna bir kod gönderiyor. Müşteri kodu giriyor, "Onayla" diyorsa işlem tamamlanıyor. Red derse veya yanlış kod girerse işlem iptal ediliyor. Her durumda banka müşteriyi sizin callback URL'nize yönlendiriyor.

Callback URL ve Güvenlik Doğrulaması

Callback URL'i ödeme başlatırken belirtmişsiniz. 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 manipüle edilebilir. Bu yüzden callback'te mutlaka doğrulama yapmalısınız - "banka gerçekten başarılı dedi mi, yoksa müşteri URL'i kendin mi değiştirdi?"

Callback için HTTP Functions kullanıyorsunuz. "http-functions.js" dosyasında post_denizbankCallback fonksiyonu oluşturun. Bu fonksiyon bankanın gönderdiği form data'yı alıyor. DenizBank birçok parametre gönderiyor ama en kritikleri şunlar:

Response: İşlem sonucu. "Approved" ise başarılı, "Declined" ise reddedilmiş, "Error" ise hata. Sadece "Approved" değerini başarılı sayın, diğer her şey başarısız.

AuthCode: Onay kodu. Başarılı işlemlerde banka bu kodu veriyor, işlemi sorgularken veya iptal ederken kullanıyorsunuz.

TransId: İşlem ID'si. Bankanın kendi sistemindeki işlem numarası. İleride iade veya iptal için bu ID'yi kullanacaksınız.

ProcReturnCode: Detaylı işlem kodu. "00" başarılı demek, diğer kodlar farklı hataları gösteriyor. "51" yetersiz bakiye, "54" kartın süresi dolmuş, "05" kart reddedilmiş gibi.

HASH: Bankanın hesapladığı hash. Siz de aynı parametrelerle hash hesaplayıp karşılaştırıyorsunuz.

Hash doğrulama yaparken dikkatli olun. DenizBank callback'te farklı parametreler kullanıyor - genellikle Response, AuthCode, TransId ve MerchantPass birleştirilip SHA-1 ile şifreleniyor. Eğer hesapladığınız hash bankanın gönderdiği HASH ile eşleşmiyorsa, veri manipüle edilmiş olabilir. İşlemi reddedin, sipariş durumunu "şüpheli" olarak işaretleyin.

Hash doğruysa Response'u kontrol edin. "Approved" görüyorsanız işlem başarılı. Sipariş durumunu "ödendi" olarak güncelleyin, AuthCode ve TransId'yi veritabanına kaydedin, müşteriye onay e-postası gönderin, envanter sistemine bildirim yapın. Response başka bir değerse işlem başarısız. Sipariş durumunu "ödeme başarısız" yapın, ProcReturnCode'a bakarak müşteriye açıklayıcı mesaj gösterin.

Çift Panel Takip Sistemi

Bağlantı tamamlandıktan sonra işlemlerinizi iki yerden takip edebiliyorsunuz. Bu sistem hem güvenlik hem de kontrol sağlıyor.

Wix Dashboard: Siparişlerin genel görünümü burada. Hangi müşteri ne aldı, sipariş numarası ne, ödeme durumu ne - bunlar Wix panelinde. Teslimat bilgileri, müşteri notları, kargo takibi gibi e-ticaret süreçleri Wix'te yönetiliyor. Wix Data kullanıyorsanız "Orders" koleksiyonunda tüm detaylar var. Sipariş durumlarını "hazırlanıyor", "kargoda", "teslim edildi" şeklinde güncelleyebiliyorsunuz.

DenizBank POS Paneli: Finansal detaylar burada. Hangi kartla ödeme yapıldı, kart son 4 hanesi, taksit sayısı, komisyon tutarı, işlem zamanı - bunları DenizBank panelinde görüyorsunuz. Panel adresi genellikle https://sanalpos.denizbank.com.tr veya https://spos.denizbank.com. Giriş yaptığınızda "İşlemler" bölümünde tüm ödemeler listeleniyor. Her işlem için detaylı bilgi görüntüleyebilir, iade yapabilir, iptal edebilirsiniz.

Bu iki panel birbirini tamamlıyor. Örneğin bir müşteri "ödeme yaptım ama sipariş oluşmadı" dediğinde önce Wix'e bakıyorsunuz - gerçekten sipariş yok mu? Sonra DenizBank paneline geçiyorsunuz - ödeme gerçekten gelmiş mi? Eğer ödeme gelmişse ama Wix'te sipariş yoksa callback sürecinde hata olmuş demektir. Logları kontrol edip sorunu tespit ediyorsunuz.

Günlük rutin olarak sabah her iki paneli de kontrol edin. DenizBank'ta gece gelen ödemeleri görüyorsunuz, Wix'te bu siparişlerin doğru işlendiğini doğruluyorsunuz. Tutarlar uyuşuyor mu? Sipariş sayıları eşleşiyor mu? Bir uyumsuzluk varsa hemen araştırın. Bazen müşteri ödeme yapmış ama sayfayı kapattığı için callback çalışmamış olabilir - bu durumları manuel düzeltmeniz gerekebilir.

Şeffaf ve Güvenli Ödeme Akışı

Bağlantı doğru yapılandırıldığında sistem şeffaf ve otomatik çalışıyor. Müşteri kart bilgilerini giriyor, bankanın sayfasına yönlendiriliyor, işlemi onaylıyor, geri sitenize dönüyor. Bu süreç 20-30 saniye sürüyor. Müşteri hiçbir karmaşık adımla karşılaşmıyor, sadece SMS şifresi giriyor.

Güvenlik katmanları şöyle sıralanıyor: İlk katman SSL sertifikası - tüm iletişim şifreli. İkinci katman hash doğrulaması - veriler manipüle edilemiyor. Üçüncü katman 3D Secure - müşteri kimliği doğrulanıyor. Dördüncü katman fraud detection - banka şüpheli işlemleri tespit ediyor. Beşinci katman callback kontrolü - işlem sonucu sunucu tarafında doğrulanıyor.

Bu katmanların hepsi arka planda çalışıyor, müşteri fark etmiyor. Onun için süreç basit - kart bilgisi gir, SMS'teki kodu gir, al alıverişini. Ama arkada beş farklı güvenlik kontrolü yapılıyor. Bu hem sizin hem müşterinizin hem de bankanın korunmasını sağlıyor.

Logları mutlaka tutun. Her ödeme başlatma, her hash hesaplama, her callback'i kaydedin. Bir sorun olduğunda loglar olmadan hata bulmak çok zor. Console.log kullanabilir veya ayrı bir log tablosu oluşturabilirsiniz. Özellikle hash hesaplamalarını loglayın - hash uyuşmazlığı en yaygın sorunlardan biri.

DenizBank'tan gelen güncelleme e-postalarını takip edin. Bazen API'de değişiklikler oluyor, yeni parametreler ekleniyor, eski endpoint'ler kapatılıyor. Bu güncellemeleri zamanında yapmazsanız sistem çalışmayı durdurabilir. Secrets Manager'daki bilgileri düzenli güncelleyin. Özellikle güvenlik anahtarını 6 ayda bir değiştirmek iyi bir pratik.

Test sürecini atlamayın. DenizBank test kartları sağlıyor - gerçek para çekilmeden tüm akışı deneyebilirsiniz. Test ortamı URL'lerini kullanın, test kartıyla birkaç işlem yapın. Başarılı senaryoyu test edin, başarısız senaryoyu da 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.

DenizBank POS'un Wix'e bağlanması, API bilgilerinin doğru işlenmesi ve güvenlik adımlarının eksiksiz uygulanmasıyla sorunsuz çalışır. Merchant ID, Store Key, Terminal ID ve güvenlik anahtarlarını Velo backend'e tanımlayın, hash hesaplamalarını doğru yapın, callback'i iyi yapılandırın. Sistem otomatik çalıştığında hem Wix hem DenizBank panelinden işlemleri takip edebilir, şeffaf ve güvenli bir ödeme akışı sağlayabilirsiniz.