Wix Garanti Sanal POS Entegrasyonu

Wix platformunda e-ticaret sitesi işleten işletmeler için Garanti BBVA Sanal POS entegrasyonu, Türkiye'nin en güçlü ödeme altyapılarından birini doğrudan kullanma imkanı sunar. Bu rehberde, Garanti BBVA sanal POS sistemini Wix Velo altyapısıyla entegre etmenin tüm teknik adımlarını, güvenlik gereksinimlerini ve en iyi uygulamaları detaylı şekilde ele alıyoruz.

Garanti BBVA Sanal POS Nedir?

Garanti BBVA Sanal POS, e-ticaret siteleri için geliştirilmiş kurumsal düzeyde bir online ödeme çözümüdür. Türkiye'nin en yaygın kullanılan sanal POS altyapılarından biri olan sistem, gelişmiş güvenlik özellikleri ve esnek ödeme seçenekleriyle öne çıkar.

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

Garanti BBVA Sanal POS'un temel özellikleri arasında 3D Secure 2.0 ile güçlendirilmiş işlem güvenliği, gelişmiş fraud koruma sistemi, Visa, Mastercard, Troy ve American Express kart desteği, 2-12 ay arası esnek taksit seçenekleri, BKM Express ve cüzdan entegrasyonları, anlık provizyon ve otomatik mutabakat ile 7/24 teknik destek hizmeti bulunur.

Garanti BBVA Sanal POS Başvuru Süreci

Entegrasyon öncesinde Garanti BBVA'dan 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 teknik entegrasyon dokümanı.

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 banka ilişkisi bulunur.

Başvuru onayı sonrası alınacak bilgiler olarak Terminal ID (9 haneli), Merchant ID (işyeri numarası), Provision Password (provizyon şifresi), 3D Secure Store Key ve API kullanıcı bilgileri sağlanır.

Entegrasyon İçin Gerekli API Bilgileri

Garanti BBVA'dan 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 Terminal ID (Terminal Numarası), Merchant ID (İşyeri Numarası), Provision Password (Provizyon Şifresi), Store Key (3D Secure Anahtarı), User ID (API Kullanıcı ID) ve User Password (API Kullanıcı Şifresi) 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 sanalposprovtest.garanti.com.tr adresi, production ortamı için sanalposprov.garanti.com.tr adresi kullanılır. 3D Secure yönlendirme URL'i olarak test için sanalposprovtest.garanti.com.tr/servlet/gt3dengine, production için sanalposprov.garanti.com.tr/servlet/gt3dengine 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 GARANTI_TERMINAL_ID, GARANTI_MERCHANT_ID, GARANTI_PROV_PASSWORD, GARANTI_STORE_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 garantiPOS.jsw adında bir dosya oluşturulur. Bu dosya ödeme başlatma fonksiyonu, hash hesaplama fonksiyonu, XML request oluşturma fonksiyonu, Garanti 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. Garanti BBVA, işlem güvenliğini sağlamak için belirli parametrelerin şifrelenmesini gerektirir. Hash değeri oluşturma sıralaması TerminalID + OrderID + Amount + SuccessURL + FailURL + Type + InstallmentCount + StoreKey + SecurityData şeklindedir. SecurityData değeri ise Password + TerminalID kombinasyonunun SHA-1 ile hashlenmesiyle oluşturulur. 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 dinamik sayfalara yönlendirir.

Dördüncü aşama: Callback endpoint oluşturma kapsamında Garanti BBVA'dan gelen yanıtları işleyecek HTTP fonksiyonları yazılır. Bu fonksiyonlar gelen verilerin hash doğrulamasını yapar, mdStatus değerini kontrol eder, işlem sonucunu değerlendirir 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. Garanti BBVA'nın 3D Secure 2.0 altyapısı, gelişmiş güvenlik özellikleri ve daha yüksek onay oranları 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 gerekli hash değerlerini hesaplar ve form verilerini hazırlar. Müşteri Garanti BBVA 3D Secure sayfasına otomatik yönlendirilir. SMS kodu, mobil uygulama onayı veya biyometrik doğrulama ile işlem onaylanır. Başarılı doğrulama sonrası Garanti callback URL'e işlem sonucunu POST eder. Backend gelen yanıtı doğrular, hash kontrolü yapar ve mdStatus değerini kontrol eder. Sipariş onaylı statüsüne

geçirilir ve stok güncellenir. Müşteri başarılı ödeme sayfasına yönlendirilir.

mdStatus değerleri ve anlamları şöyledir: 1 değeri tam doğrulamayı (Full 3D Authentication) ifade eder ve işlem onaylanmalıdır. 2 değeri kart sahibinin bankası veya kartın sisteme kayıtlı olmadığını gösterir. 3 değeri kartın sisteme kayıtlı olmadığını belirtir. 4 değeri doğrulama denemesi yapıldığını (kart sahibi sisteme daha sonra kayıt olmayı seçmiş) gösterir. 5 değeri doğrulama yapılamadığını ifade eder. 6 değeri 3D Secure hatası olduğunu gösterir. 7 değeri sistem hatası olduğunu belirtir. 0 değeri doğrulama başarısız olduğunu veya kullanıcının şifresini yanlış girdiğini gösterir.

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

Garanti BBVA 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 Number parametresi taksit sayısını belirtir. Tek çekim için bu değer boş bırakılır veya 0 gönderilir.

Desteklenen taksit seçenekleri genellikle 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ve 12 taksit şeklindedir. Kampanya dönemlerinde özel taksit seçenekleri sunulabilir. Taksit vade farkı oranları Garanti BBVA'nın belirlediği tarifeye göre değişir.

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

Kampanya entegrasyonu kapsamında Garanti POS panelinden tanımlanan kampanyalar, CampaignCode parametresiyle ödeme isteğine eklenebilir. Karta özel indirimler 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 Garanti BBVA hata kodları ve açıklamaları şöyledir: 00 kodu başarılı işlemi, 01 kodu kartı veren bankayı araması gerektiğini, 02 kodu kartı veren bankayı araması gerektiğini, 05 kodu onaylanmayan işlemi (red), 12 kodu geçersiz işlemi, 13 kodu geçersiz tutarı, 14 kodu geçersiz kart numarasını, 33 kodu süresi dolmuş kartı, 34 kodu sahte kartı veya şüpheli işlemi, 41 kodu kayıp veya çalıntı kartı, 43 kodu çalıntı kartı, 51 kodu yetersiz bakiyeyi, 54 kodu kartın son kullanma tarihinin geçtiğini, 57 kodu kart sahibine açık olmayan işlemi, 58 kodu terminale tanımlı olmayan işlemi, 62 kodu kısıtlanmış kartı, 65 kodu günlük işlem adedinin aşıldığını, 75 kodu hatalı şifre deneme sayısının aşıldığını, 91 kodu bankadan yanıt alınamadığını ve 96 kodu sistem arızası olduğunu gösterir.

Hata loglama stratejisi olarak tüm API istekleri ve yanıtları loglanmalı, hassas bilgiler (kart numarası, CVV, şifre) 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 ve müşteri güvenini sağlar.

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ır.

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.

Ek güvenlik katmanları olarak rate limiting (dakikada maksimum istek sınırı), IP whitelist (belirli IP adreslerinden gelen isteklerin kabul edilmesi), request signature (her isteğin imzalanması), velocity check (kısa sürede çok fazla işlem engelleme) ve BIN kontrolü (şüpheli BIN aralıklarının izlenmesi) uygulanabilir.

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

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

Test ortamı bilgileri olarak test endpoint adresi sanalposprovtest.garanti.com.tr şeklindedir. Test kartı numarası olarak 5549608789641500 kullanılabilir. Son kullanma tarihi 12/30, CVV 000, 3D Secure şifresi a olarak belirlenmiştir.

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, yanlış 3D şifre 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 Garanti 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 Garanti BBVA'nın iade API'si kullanılır. Type parametresi refund olarak ayarlanır. OriginalRetrefNum (orijinal işlem referans numarası) ile çağrı yapılır. İade tutarı belirtilir. İade işlemleri genellikle 1-3 iş günü içinde kart sahibinin hesabına yansır.

Provizyon iptali yalnızca aynı gün içinde, gün sonu kapanışından önce yapılabilir. Type parametresi void olarak ayarlanır. Tutar iadesi anında gerçekleşir.

Manuel işlemler için Garanti 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 Garanti panelinden izlenebilir. Çift taraflı kontrol, mutabakat sürecini kolaylaştırır.

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.

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

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

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ümentasyona uygunluğu kontrol edilmeli, encoding (UTF-8) doğrulanmalı, tutar formatı kontrol edilmeli (kuruş cinsinden, nokta veya virgül olmadan), SecurityData hesaplamasının doğruluğu teyit edilmeli ve StoreKey değerinin doğruluğu kontrol 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 Garanti API yanıt süreleri kontrol edilmeli, retry mekanizması eklenmeli ve timeout süresi artırılmalıdır (önerilen 30-60 saniye).

mdStatus hatası için 3D Secure şifresinin doğru girilip girilmediği kontrol edilmeli, kartın 3D Secure'a kayıtlı olup olmadığı doğrulanmalı ve banka tarafında 3D Secure limitlerinin aşılıp aşılmadığı kontrol edilmelidir.

Garanti BBVA Sanal POS entegrasyonu, Wix e-ticaret sitenize Türkiye'nin en güçlü ödeme altyapılarından birini kazandırır. Doğru yapılandırıldığında 3D Secure 2.0 güvenliği, esnek taksit seçenekleri, kampanya yönetimi 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.

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