Wix Akbank Sanal POS Kurulumu: Güvenli Ödeme Entegrasyonu Rehberi | Blakfy

Wix platformunda e-ticaret sitesi işleten işletmeler için Akbank Sanal POS entegrasyonu, müşterilere güvenli ve taksitli ödeme imkanı sunmanın profesyonel yoludur. Bu kapsamlı rehberde, Akbank sanal POS sistemini Wix Velo altyapısıyla entegre etmenin tüm teknik adımlarını ve dikkat edilmesi gereken noktaları detaylı şekilde ele alıyoruz.

Akbank Sanal POS Nedir?

Akbank Sanal POS, e-ticaret siteleri için geliştirilmiş kapsamlı bir online ödeme çözümüdür. 3D Secure 2.0 teknolojisi sayesinde kart sahibi kimlik doğrulaması yapılır ve işlem güvenliği en üst seviyede sağlanır. Sistem, tek çekim satışların yanı sıra 2-12 ay arası taksitli ödeme seçenekleri sunar.

Wix platformuyla entegrasyon, Velo by Wix geliştirme ortamı üzerinden gerçekleştirilir. Bu entegrasyon sayesinde standart Wix ödeme yöntemlerinin ötesine geçilerek tamamen özelleştirilmiş ödeme akışları oluşturulabilir.

Akbank Sanal POS'un temel özellikleri arasında 3D Secure 2.0 ile güçlendirilmiş işlem güvenliği, Visa, Mastercard, Troy ve American Express kart desteği, esnek taksit seçenekleri ve kampanya yönetimi, anlık provizyon ve otomatik gün sonu mutabakatı, mobil ödeme ve temassız işlem uyumluluğu ile 7/24 teknik destek hizmeti yer alır.

Akbank Sanal POS Başvuru Süreci

Entegrasyon öncesinde Akbank'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, web sitesi URL'i ve teknik entegrasyon bilgileri. Başvuru onaylandıktan sonra Akbank tarafından entegrasyon için gerekli tüm API bilgileri güvenli kanallar aracılığıyla iletilir.

Başvuru değerlendirme kriterleri arasında işletmenin faaliyet süresi, aylık tahmini ciro, sektör risk değerlendirmesi ve web sitesinin içerik uygunluğu bulunur.

Entegrasyon İçin Gerekli API Bilgileri

Akbank'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 ClientId (İşyeri Kimlik Numarası), StoreKey (Mağaza Güvenlik Anahtarı), Username (API Kullanıcı Adı), Password (API Şifresi), Terminal ID (Terminal Numarası) ve 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. Bilgilerin yanlış ellere geçmesi durumunda ciddi finansal ve güvenlik riskleri oluşabilir.

Wix Velo Geliştirme Ortamı Hazırlığı

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 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 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 ve isimlendirme standart tutulur (örneğin AKBANK_CLIENT_ID, AKBANK_STORE_KEY).

Gerekli npm paketleri olarak wix-secrets-backend, wix-fetch, crypto-js ve wix-stores-backend kurulmalı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 payment.jsw adında bir dosya oluşturulur. Bu dosya ödeme başlatma fonksiyonu, hash hesaplama fonksiyonu, Akbank API iletişim fonksiyonu, callback doğrulama fonksiyonu ve sipariş güncelleme fonksiyonunu içerir.

İkinci aşama: Hash hesaplama algoritması entegrasyonun en kritik bileşenidir. Akbank, işlem güvenliğini sağlamak için belirli parametrelerin şifrelenmesini gerektirir. Hash değeri oluşturma sıralaması ClientId + OrderId + Amount + OkUrl + FailUrl + TranType + InstallmentCount + StoreKey şeklindedir. Bu parametreler birleştirilerek SHA-512 algoritmasıyla şifrelenir.

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

Dördüncü aşama: Callback endpoint oluşturma kapsamında Akbank'tan gelen yanıtları işleyecek HTTP fonksiyonları yazılır. Bu fonksiyonlar gelen verilerin hash doğrulamasını yapar, işlem sonucunu kontrol eder ve sipariş durumunu günceller.

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. Akbank'ın 3D Secure 2.0 altyapısı, gelişmiş güvenlik özellikleri sunar.

Ö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 Akbank'a ödeme başlatma isteği gönderir ve müşteri Akbank 3D Secure sayfasına yönlendirilir. SMS, mobil uygulama veya biyometrik doğrulama ile onay yapılır. Başarılı doğrulama sonrası Akbank 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 2.0 avantajları arasında frictionless flow ile düşük riskli işlemlerde doğrulama adımının atlanabilmesi, biyometrik doğrulama desteği, daha hızlı işlem süresi, gelişmiş fraud koruması ve daha yüksek onay oranları bulunur.

Taksit Yapılandırması ve Kampanya Yönetimi

Akbank Sanal POS, kapsamlı taksit seçenekleri ve kampanya yönetimi imkanı sunar. Taksitli satışlar, müşteri dönüşüm oranlarını önemli ölçüde artırır.

Taksit parametreleri olarak InstallmentCount (taksit sayısı) ve TotalInstallment (toplam taksit) değerleri ödeme isteğine eklenir. Tek çekim için InstallmentCount değeri 0 veya 1 olarak gönderilir.

Desteklenen taksit seçenekleri genellikle 2, 3, 4, 5, 6, 9 ve 12 taksit şeklindedir. Kampanya dönemlerinde 18 veya 24 taksit seçenekleri de sunulabilir. Taksit vade farkı oranları Akbank'ın belirlediği tarifeye göre değişir.

Kampanya yönetimi için Akbank POS panelinden karta özel kampanyalar tanımlanabilir. Belirli BIN aralıklarına özel indirimler uygulanabilir. Minimum tutar şartlı taksit kampanyaları oluşturulabilir.

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 Akbank hata kodları ve açıklamaları şöyledir: 00 kodu başarılı işlemi, 05 kodu onaylanmayan kartı (müşteri bankasıyla iletişime geçmeli), 12 kodu geçersiz işlemi (kart bilgileri kontrol edilmeli), 14 kodu geçersiz kart numarasını, 33 kodu süresi dolmuş kartı, 41 kodu kayıp kartı, 43 kodu çalıntı kartı, 51 kodu yetersiz bakiyeyi, 54 kodu kartın son kullanma tarihinin geçtiğini, 61 kodu günlük işlem limitinin aşıldığını, 65 kodu günlük işlem adedinin aşıldığını ve 91 kodu bankanın yanıt vermediğini (tekrar denenmeli) gösterir.

Hata loglama stratejisi olarak tüm API istekleri ve yanıtları loglanmalı, hassas bilgiler (kart numarası, CVV) kesinlikle loglanmamalı, hata anında timestamp, işlem ID ve hata kodu 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ı, IP whitelist yapılandırması ve düzenli güvenlik denetimleri yer alır.

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

Ek güvenlik katmanları olarak rate limiting (dakikada maksimum istek sınırı), request signature (her isteğin imzalanması), SSL pinning (sertifika sabitleme) ve fraud detection kuralları uygulanabilir.

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

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

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, yetersiz bakiye senaryosu, geçersiz kart numarası senaryosu, süresi dolmuş kart senaryosu, 3D Secure timeout 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 Akbank 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ı), kısmi iade (işlem tutarının bir kısmı) ve provizyon iptali (aynı gün içinde yapılan işlemin iptali) bulunur.

Otomatik iade entegrasyonu için Akbank'ın iade API'si kullanılır. Orijinal işlem referans numarası (HostRefNum) 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 iade için Akbank 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 İzleme

Başarılı entegrasyon sonrası ödeme hareketleri hem Wix hem Akbank 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.

Akbank POS panelinde izleme kapsamında günlük işlem özeti, taksit dağılımı raporu, kart tipi bazlı analiz, iade ve iptal raporu ile mutabakat raporları görüntülenebilir.

Önerilen KPI'lar olarak günlük/haftalık/aylık işlem hacmi, ortalama sepet tutarı, taksit kullanım oranı, başarılı işlem oranı, iade oranı ve chargeback oranı takip edilmelidir.

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ı kontrol edilmeli, encoding (UTF-8) doğrulanmalı, boşluk ve özel karakterler kontrol edilmeli ve StoreKey doğruluğu teyit edilmelidir.

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

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

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

Akbank Sanal POS entegrasyonu, Wix e-ticaret sitenize kurumsal düzeyde bir ödeme altyapısı kazandırır. 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.

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