Wix Finansbank Sanal POS Entegrasyonu

Wix platformunda e-ticaret sitesi işleten işletmeler için QNB Finansbank Sanal POS entegrasyonu, Türkiye'nin önde gelen bankalarından birinin güvenilir ödeme altyapısını kullanma imkanı sunuyor. Dijital odaklı yaklaşımı, gelişmiş teknolojik altyapısı ve CardFinans avantajlarıyla öne çıkan QNB Finansbank, e-ticaret işletmeleri için güçlü bir ödeme çözümü sağlıyor.

QNB Finansbank Sanal POS Nedir?

QNB Finansbank Sanal POS, e-ticaret siteleri için geliştirilmiş kapsamlı bir online ödeme çözümüdür. Katar merkezli QNB Group'un Türkiye'deki bankası olarak global standartlarda teknoloji ve yerel pazar bilgisini birleştiren sistem, özellikle dijital odaklı işletmeler için ideal bir tercih oluşturuyor.

Wix platformuyla entegrasyon, Velo by Wix geliştirme ortamı üzerinden gerçekleştirilir. Bu entegrasyon sayesinde standart Wix ödeme yöntemlerinin ötesine geçilerek QNB Finansbank'ın tüm özelliklerinden faydalanılabilir.

QNB Finansbank Sanal POS'un temel özellikleri arasında 3D Secure 2.0 ile güçlendirilmiş işlem güvenliği, gelişmiş fraud detection ve koruma sistemleri, Visa, Mastercard, Troy ve American Express kart desteği, CardFinans kart programı avantajları, 2-12 ay arası esnek taksit seçenekleri, hızlı işlem onayı ve düşük latency, dijital öncelikli modern API altyapısı ile 7/24 teknik destek hizmeti bulunuyor.

QNB Finansbank POS'un avantajları değerlendirildiğinde global banka gücüyle yerel uzmanlık kombinasyonu, CardFinans müşteri tabanına erişim, rekabetçi komisyon oranları ve esnek paketler, modern ve geliştirici dostu API yapısı ile hızlı başvuru ve onay süreçleri öne çıkıyor.

QNB Finansbank Sanal POS Başvuru Süreci

Entegrasyon öncesinde QNB Finansbank'tan sanal POS başvurusu yapılması ve onaylanması gerekir. Başvuru süreci genellikle 5-10 iş günü içinde tamamlanır.

Başvuru için gerekli belgeler şunlardır: Güncel vergi levhası, noter onaylı imza sirküleri, ticaret sicil gazetesi sureti, faaliyet belgesi, şirket yetkilisi kimlik fotokopisi, web sitesi URL'i ve içerik bilgisi ile banka hesap cüzdanı fotokopisi.

Başvuru değerlendirme kriterleri arasında işletmenin faaliyet süresi ve sicil kaydı, aylık tahmini e-ticaret cirosu, sektör risk değerlendirmesi, web sitesinin içerik ve güvenlik uygunluğu ile mevcut QNB Finansbank ilişkisi bulunuyor.

Başvuru kanalları olarak QNB Finansbank şubeleri, online başvuru portalı, ticari bankacılık temsilcisi ve Finansbank işletme bankacılığı hattı kullanılabilir.

Başvuru onayı sonrası alınacak bilgiler olarak Merchant ID (MbrId - Üye İşyeri Numarası), Terminal ID (MerchantId), User Code (Kullanıcı Kodu), User Pass (Kullanıcı Şifresi), 3D Secure Store Key (ENCKEY) ve API endpoint bilgileri sağlanır.

Entegrasyon İçin Gerekli API Bilgileri

QNB Finansbank'tan sanal POS onayı alındıktan sonra banka tarafından sağlanan API bilgileri entegrasyon için kullanılır. Bu bilgiler kritik öneme sahiptir ve güvenli şekilde saklanmalıdır.

Temel API parametreleri olarak MbrId (Üye İşyeri Numarası - 5 haneli), MerchantId (İşyeri Kodu - 16 haneli), MerchantPass (İşyeri Şifresi), UserCode (Kullanıcı Kodu), UserPass (Kullanıcı Şifresi) ve SecureKey (3D Secure şifreleme anahtarı) alınır.

Bu bilgiler son derece hassastır ve kesinlikle frontend kodlarında bulunmamalıdır. Wix Secrets Manager, bu tür gizli bilgilerin güvenli şekilde depolanması için ideal çözüm sunar.

API endpoint bilgileri olarak test ortamı için vpostest.qnbfinansbank.com adresi, production ortamı için vpos.qnbfinansbank.com adresi kullanılır. 3D Secure yönlendirmesi için test ortamında vpostest.qnbfinansbank.com/Gateway/3DHost.aspx, production ortamında vpos.qnbfinansbank.com/Gateway/3DHost.aspx adresleri geçerlidir.

Wix Velo Geliştirme Ortamı Kurulumu

Entegrasyona başlamadan önce Wix Velo geliştirme ortamının doğru şekilde yapılandırılması gerekir.

Velo'yu aktifleştirme adımları şu şekildedir: Wix Editor'da üst menüden Dev Mode butonuna tıklanarak Velo aktifleştirilir. Sol panelde Code Files bölümü görünür hale gelir. Backend klasörü altında yeni .jsw ve .js dosyaları oluşturulabilir. Public klasörü frontend kodları için kullanılır.

Secrets Manager yapılandırması için Wix Dashboard'dan Settings bölümüne gidilir. Secrets Manager seçeneği açılır. Her API bilgisi için ayrı secret oluşturulur. İsimlendirme standart tutulmalıdır, örneğin FINANSBANK_MBR_ID, FINANSBANK_MERCHANT_ID, FINANSBANK_MERCHANT_PASS, FINANSBANK_SECURE_KEY şeklinde.

Gerekli modüller ve paketler olarak wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data ve crypto-js kurulmalı veya içe aktarılmalıdır.

Teknik Entegrasyon Adımları

Entegrasyon süreci beş temel aşamadan oluşur. Her aşamanın doğru tamamlanması sistemin sorunsuz çalışması için kritik öneme sahiptir.

Birinci aşama: Backend servis dosyası oluşturma kapsamında Wix'in backend klasöründe finansbankPOS.jsw adında bir dosya oluşturulur. Bu dosya ödeme başlatma fonksiyonu, hash hesaplama fonksiyonu, API request builder fonksiyonu, QNB Finansbank API iletişim fonksiyonu, 3D Secure callback doğrulama fonksiyonu ve sipariş güncelleme fonksiyonunu içerir.

İkinci aşama: Hash hesaplama algoritması entegrasyonun en kritik bileşenidir. QNB Finansbank, işlem güvenliğini sağlamak için hash değeri gerektirir. Hash değeri oluşturma sıralaması MbrId + OrderId + Amount + OkUrl + FailUrl + TxnType + InstallmentCount + Rnd + SecureKey şeklindedir. Bu parametreler birleştirilerek SHA-512 algoritmasıyla şifrelenir ve Base64 encode edilir.

Üçüncü aşama: 3D Secure yönlendirme yapılandırması için iki adet callback URL tanımlanır. OkUrl (Success URL) başarılı işlemler için, FailUrl (Fail URL) başarısız işlemler için kullanılır. Bu URL'ler Wix sitenizde oluşturulacak dinamik sayfalara yönlendirir.

Dördüncü aşama: Callback endpoint oluşturma kapsamında QNB Finansbank'tan gelen yanıtları işleyecek HTTP fonksiyonları yazılır. Bu fonksiyonlar gelen verilerin parse edilmesini, hash doğrulamasını, işlem sonucunun değerlendirilmesini ve sipariş durumunun güncellenmesini gerçekleştirir.

Beşinci aşama: Frontend entegrasyonu ile ödeme formu ve kullanıcı arayüzü bağlantısı kurulur. Kart bilgileri güvenli şekilde alınır ve backend fonksiyonları çağrılır.

3D Secure Ödeme Akışı Detayları

3D Secure, online ödemelerde kart sahibi doğrulaması sağlayan güvenlik protokolüdür. QNB Finansbank'ın 3D Secure 2.0 altyapısı, gelişmiş güvenlik özellikleri ve modern kullanıcı deneyimi sunuyor.

Ödeme akışı şu şekilde işler: Müşteri sepet sayfasında ödeme butonuna tıklar ve kart bilgilerini güvenli form alanlarına girer. Sistem arka planda gerekli hash değerlerini hesaplar ve form verilerini hazırlar. Müşteri QNB Finansbank 3D Secure sayfasına otomatik yönlendirilir. SMS kodu veya QNB Mobil uygulama onayı ile işlem doğrulanır. Başarılı doğrulama sonrası banka callback URL'e işlem sonucunu POST eder. Backend gelen yanıtı doğrular ve hash kontrolü yapar. Sipariş onaylı statüsüne geçirilir ve stok güncellenir. Müşteri başarılı ödeme sayfasına yönlendirilir.

3D Secure yanıt parametreleri şöyle değerlendirilir: ProcReturnCode değeri 00 ise işlem başarılıdır. Status değeri Y (doğrulandı), N (doğrulanamadı), U (doğrulama yapılamadı) veya A (deneme yapıldı) olabilir. ErrMsg hata durumunda açıklama mesajı içerir. AuthCode başarılı işlemlerde provizyon kodu sağlar.

Taksit Yapılandırması ve CardFinans Avantajları

QNB Finansbank Sanal POS, kapsamlı taksit seçenekleri ve CardFinans kart programı avantajları sunuyor. CardFinans müşterilerine özel kampanyalar, dönüşüm oranlarını artırır.

Taksit parametreleri olarak InstallmentCount parametresi taksit sayısını belirtir. Tek çekim için bu değer 0 veya boş gönderilir. Taksitli işlemler için 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 değerleri kullanılır.

CardFinans avantajları kapsamında CardFinans kart sahiplerine özel ek taksit imkanı, puan kazanım ve harcama kampanyaları, CardFinans mobil uygulama entegrasyonu ve özel gün kampanyaları (yılbaşı, bayram, vs.) sunuluyor.

BIN bazlı taksit sorgulama için kart numarasının ilk 6 hanesini kullanarak o karta uygulanabilecek taksit seçenekleri sorgulanabilir. Bu sorgu, müşteriye yalnızca geçerli taksit seçeneklerinin gösterilmesini sağlar.

Kampanya entegrasyonu yapılırken QNB Finansbank POS panelinden tanımlanan kampanyalar API üzerinden sorgulanabilir. Karta özel indirimler ve ek taksitler otomatik uygulanır.

Hata Yönetimi ve Hata Kodları

Ödeme entegrasyonlarında kapsamlı hata yönetimi kritik öneme sahiptir. Kullanıcıya anlaşılır mesajlar gösterilirken teknik detaylar loglanmalıdır.

Yaygın QNB Finansbank hata kodları ve açıklamaları şöyledir: 00 kodu başarılı işlemi, 01 kodu kartı veren bankayı aramayı, 02 kodu kartı veren bankayı aramayı, 03 kodu geçersiz üye işyerini, 04 kodu karta el konulmasını, 05 kodu onaylanmayan işlemi, 06 kodu geçersiz işlemi, 07 kodu karta el konulmasını (fraud), 08 kodu sahte onayı, 09 kodu tekrar denenmesini, 12 kodu geçersiz işlemi, 13 kodu geçersiz tutarı, 14 kodu geçersiz kart numarasını, 15 kodu geçersiz kartı veren bankayı, 33 kodu süresi dolmuş kartı, 34 kodu fraud şüphesini, 36 kodu kısıtlı kartı, 41 kodu kayıp kartı, 43 kodu çalıntı kartı, 51 kodu yetersiz bakiyeyi, 52 kodu hesap numarasının kontrol edilmesini, 53 kodu hesap bulunamadığını, 54 kodu son kullanma tarihinin geçtiğini, 55 kodu yanlış PIN'i, 56 kodu kartın kaydının olmadığını, 57 kodu kart sahibine izin verilmeyen işlemi, 58 kodu terminale izin verilmeyen işlemi, 61 kodu günlük limitin aşıldığını, 62 kodu kısıtlanmış kartı, 63 kodu güvenlik ihlalini, 65 kodu günlük işlem adedinin aşıldığını, 75 kodu PIN deneme hakkının aşıldığını, 91 kodu kartı veren bankadan yanıt alınamadığını ve 96 kodu sistem arızasını gösterir.

Hata loglama stratejisi olarak tüm API istekleri ve yanıtları loglanmalı, hassas bilgiler (kart numarası, CVV, PIN) kesinlikle loglanmamalı, hata anında timestamp, işlem ID, hata kodu ve hata mesajı kaydedilmeli ve production ortamında kapsamlı loglama çözümü kullanılmalıdır.

Güvenlik Önlemleri ve PCI DSS Uyumu

Ödeme entegrasyonlarında güvenlik en yüksek önceliğe sahiptir. PCI DSS standartlarına uyum yasal zorunluluktur.

Temel güvenlik gereksinimleri arasında API bilgilerinin asla frontend kodlarında bulunmaması, tüm hassas verilerin Secrets Manager'da saklanması, HTTPS protokolünün zorunlu kullanımı, hash doğrulamasının her işlemde yapılması ve düzenli güvenlik denetimleri gerçekleştirilmesi yer alıyor.

PCI DSS uyumu için kart bilgileri sunucularınızda saklanmamalı, tokenizasyon hizmetleri kullanılmalı, güvenlik açığı taramaları düzenli yapılmalı, erişim logları tutulmalı ve personel güvenlik eğitimi verilmelidir.

QNB Finansbank ek güvenlik özellikleri olarak gelişmiş fraud detection algoritmaları, velocity check (hız kontrolü) sistemi, BIN bazlı risk değerlendirmesi, IP bazlı filtreleme imkanı ve şüpheli işlem uyarı sistemi sunuluyor.

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

Entegrasyon tamamlandıktan sonra kapsamlı test süreci zorunludur. QNB Finansbank, test ortamı için ayrı endpoint ve test kartları sağlar.

Test ortamı bilgileri olarak test endpoint adresi vpostest.qnbfinansbank.com üzerinden sağlanır. Test kartı bilgileri QNB Finansbank tarafından başvuru onayı sonrası iletilir.

Test senaryoları kontrol listesi olarak başarılı tek çekim ödeme, başarılı 3 taksitli ödeme, başarılı 6 taksitli ödeme, başarılı 12 taksitli ödeme, CardFinans kartı ile ödeme, yetersiz bakiye senaryosu, geçersiz kart numarası senaryosu, süresi dolmuş kart senaryosu, 3D Secure timeout senaryosu, hatalı SMS kodu senaryosu, başarılı tam iade işlemi, başarılı kısmi iade işlemi ve provizyon iptal işlemi test edilmelidir.

Canlıya geçiş adımları şu şekildedir: Tüm test senaryoları başarıyla tamamlanır. Test ortamı bilgileri production bilgileriyle değiştirilir. Endpoint URL'leri production URL'leriyle güncellenir. İlk gerçek işlem düşük tutarla test edilir. İşlem hem Wix panelinden hem QNB Finansbank POS panelinden doğrulanır.

İade ve İptal İşlemleri

Satış sonrası iade ve provizyon iptali işlemleri hem manuel hem otomatik olarak gerçekleştirilebilir.

İade türleri olarak tam iade (işlem tutarının tamamı - TxnType: Refund), kısmi iade (işlem tutarının bir kısmı - TxnType: Refund ile tutar belirtilerek) ve provizyon iptali (aynı gün içinde, gün sonu öncesi - TxnType: Void) bulunuyor.

Otomatik iade entegrasyonu için QNB Finansbank'ın iade API'si kullanılır. Orijinal işlem referans numarası (OrderId veya AuthCode) ile çağrı yapılır. İade tutarı ve para birimi belirtilir. İade işlemleri genellikle 1-3 iş günü içinde kart sahibinin hesabına yansır.

Manuel işlemler için QNB Finansbank POS yönetim paneline giriş yapılır. İşlem geçmişinden ilgili işlem bulunur. İade veya iptal seçeneği seçilir ve tutar girilip onaylanır.

Raporlama ve Mutabakat

Başarılı entegrasyon sonrası ödeme hareketleri hem Wix hem QNB Finansbank panelinden izlenebilir.

Wix tarafında izleme için Wix Stores Dashboard'dan siparişler takip edilir. Ödeme durumları (beklemede, onaylı, iptal) görüntülenir. Özel raporlama için Wix Analytics kullanılabilir.

QNB Finansbank POS panelinde izleme kapsamında günlük işlem özeti, taksit dağılımı raporu, kart tipi bazlı analiz (CardFinans, Visa, Mastercard), iade ve iptal raporu, mutabakat raporları, komisyon detay raporu ve CardFinans kampanya raporları görüntülenebilir.

Otomatik mutabakat için gün sonu kapanışı otomatik veya manuel yapılandırılabilir. Mutabakat saati QNB Finansbank POS panelinden ayarlanır. Günlük mutabakat raporu e-posta ile gönderilebilir.

Sektörel Kullanım Önerileri

QNB Finansbank Sanal POS, farklı sektörlerin ihtiyaçlarına uygun çözümler sunuyor.

E-ticaret mağazaları için taksitli satış ile sepet değerini artırma, CardFinans kampanyalarıyla müşteri çekme, hızlı checkout deneyimi ve stok yönetimi entegrasyonu önerilir.

Hizmet sektörü için danışmanlık ödemeleri, abonelik sistemleri, tek seferlik hizmet ödemeleri ve fatura bazlı tahsilat uygulanabilir.

Eğitim platformları için kurs kayıt ödemeleri, taksitli eğitim paketleri, online ders ödemeleri ve sertifika programı tahsilatları yapılabilir.

Sağlık sektörü için hasta ödemeleri, taksitli tedavi planları, online randevu ödemeleri ve check-up paket satışları gerçekleştirilebilir.

Sık Karşılaşılan Sorunlar ve Çözümleri

Entegrasyon sürecinde karşılaşılabilecek yaygın sorunlar ve çözüm önerileri aşağıda yer almaktadır.

Hash doğrulama hatası için parametre sıralamasının dokümantasyona uygunluğu kontrol edilmeli, encoding (UTF-8) doğrulanmalı, tutar formatı kontrol edilmeli (kuruş dahil, nokta veya virgül olmadan), SecureKey değerinin doğruluğu teyit edilmeli ve Base64 encoding doğru uygulanmalıdır.

3D Secure yönlendirme sorunu için callback URL'lerin erişilebilirliği kontrol edilmeli, SSL sertifikası doğrulanmalı, URL'lerin HTTPS olduğu kontrol edilmeli ve Wix site ayarlarında external redirects izni verilmelidir.

Timeout hataları için QNB Finansbank API yanıt süreleri kontrol edilmeli, retry mekanizması eklenmeli ve timeout süresi artırılmalıdır (önerilen 45-60 saniye).

Taksit görünmeme sorunu için POS tanımında taksit yetkisi kontrol edilmeli, minimum tutar şartları doğrulanmalı, kart BIN kontrolü yapılmalı ve kampanya tanımları kontrol edilmelidir.

QNB Finansbank Sanal POS entegrasyonu, Wix e-ticaret sitenize modern ve güvenilir bir ödeme altyapısı kazandırır. Dijital odaklı yaklaşımı, gelişmiş fraud koruma sistemleri, CardFinans avantajları ve rekabetçi komisyon oranlarıyla QNB Finansbank, e-ticaret işletmeleri için güçlü bir tercih oluşturur. Doğru yapılandırıldığında 3D Secure 2.0 güvenliği, esnek taksit seçenekleri ve sorunsuz bir müşteri deneyimi sunabilirsiniz. Teknik karmaşıklık ve güvenlik gereksinimleri nedeniyle bu entegrasyonun deneyimli bir geliştirici tarafından yapılması önerilir.

QNB Finansbank Sanal POS entegrasyonu ve Wix e-ticaret çözümleri için Blakfy ile iletişime geçin: blakfy.com/iletisim