Wix ile Garanti POS Entegrasyonu: Detaylı Teknik Rehber

Wix platformunda Garanti BBVA sanal POS entegrasyonu yapmak, e-ticaret işletmelerinin güvenli ödeme altyapısı kurmasında kritik öneme sahiptir. Bu entegrasyon süreci, teknik altyapı kurulumundan güvenlik protokollerine kadar birçok aşamayı içermektedir.

Ön Hazırlık ve Gerekli Belgeler

Entegrasyon sürecine başlamadan önce Garanti BBVA ile ticari anlaşma yapılması ve sanal POS başvurusunun tamamlanması gerekmektedir. Bu süreçte işletmenize özel olarak Terminal ID (Terminal Numarası), Merchant ID (Üye İşyeri Numarası), Provision User ID ve Provision Password gibi kritik kimlik bilgileri tahsis edilir. Bu bilgiler tüm API iletişiminin temelini oluşturur ve güvenli bir şekilde saklanmalıdır.

Garanti BBVA'nın resmi geliştirici portalı olan garanti.com.tr/tr/isyerleri/sanal-pos adresinde sanal POS hizmetleri hakkında genel bilgilere ulaşabilirsiniz. Teknik dokümantasyon için ise sanalposdokumantasyon.garanti.com.tr adresini ziyaret etmeniz önerilir. Bu kaynaklar API referansları, örnek kodlar ve entegrasyon kılavuzları sunmaktadır.

Velo Backend Altyapısının Kurulumu

Wix platformunun sunduğu Velo kod ortamı, Garanti POS entegrasyonunun kalbi konumundadır. Velo, Wix sitelerinize özel backend fonksiyonları eklemenize olanak tanıyan JavaScript tabanlı bir geliştirme ortamıdır. Entegrasyon için backend klasörünüzde HTTP modülünü kullanarak Garanti API'sine bağlantı kurmanız gerekmektedir.

İlk adım olarak wix-fetch modülünü kullanarak Garanti API endpoint'lerine istek gönderecek fonksiyonlar oluşturulmalıdır. Test ortamı için sanalposprovtest.garanti.com.tr adresi, canlı ortam için ise sanalposprov.garanti.com.tr adresi kullanılır. Bu ayrım, geliştirme sürecinde gerçek ödeme işlemlerini riske atmadan test yapmanızı sağlar.

Backend'de oluşturulacak temel fonksiyonlar ödeme başlatma, hash oluşturma, 3D Secure doğrulama ve işlem sonuç kontrolünü kapsamalıdır. Her fonksiyon için hata yönetimi ve loglama mekanizmaları mutlaka eklenmelidir. Velo'nun Secrets Manager özelliğini kullanarak API anahtarlarınızı güvenli bir şekilde saklayabilirsiniz, böylece hassas bilgiler kodunuzda açık olarak görünmez.

Hash Algoritması ve Güvenlik Katmanları

Garanti BBVA sanal POS entegrasyonunun en kritik güvenlik unsuru SHA-512 hash algoritmasıdır. Bu algoritma, işlem verilerinin bütünlüğünü garanti altına alır ve yetkisiz değişiklikleri önler. Hash oluşturma süreci belirli bir sıraya göre gerçekleştirilmelidir.

Hash hesaplaması için Terminal ID, Order ID (sipariş numarası), tutar bilgisi, kredi kartı numarasının son dört hanesi, success ve error URL'leri ile provision password birleştirilerek SHA-512 algoritmasından geçirilir. Bu işlem sonucunda 128 karakterlik bir hash değeri elde edilir. Garanti API'sine gönderilen her istekte bu hash değeri bulunmalı ve banka tarafından doğrulanmalıdır.

Callback aşamasında ise bankadan dönen hash değerinin sunucu tarafında yeniden hesaplanıp karşılaştırılması kritik önem taşır. Bu doğrulama yapılmadan işlem sonucuna güvenilmemeli ve sipariş durumu güncellenmemelidir. Aksi takdirde sahte işlem bildirimleriyle sistem manipüle edilebilir.

3D Secure Ödeme Akışı

Garanti BBVA'nın 3D Secure sistemi, kart sahibinin kimliğini doğrulamak için ek bir güvenlik katmanı sağlar. Ödeme işlemi başlatıldığında kullanıcı otomatik olarak bankanın 3D Secure sayfasına yönlendirilir. Bu sayfada kart sahibi, telefon numarasına gelen SMS kodu veya mobil uygulama üzerinden onay vererek işlemi tamamlar.

Yönlendirme işlemi için bir HTML formu oluşturulmalı ve bu form POST metodu ile Garanti'nin 3D Secure gateway adresine gönderilmelidir. Form içerisinde Terminal ID, Merchant ID, sipariş numarası, tutar, taksit bilgisi, kart bilgileri ve hash değeri bulunmalıdır. Wix sitenizdeki checkout sayfasında bu formu dinamik olarak oluşturup submit etmeniz gerekir.

3D Secure doğrulama tamamlandığında banka, önceden belirttiğiniz success veya error callback URL'lerine kullanıcıyı yönlendirir. Bu URL'ler Velo backend'de tanımlanmış HTTP fonksiyonlar olmalıdır. Callback verilerini alıp işleyen bu fonksiyonlar, hash doğrulaması yaptıktan sonra işlem sonucunu veritabanınıza kaydeder ve kullanıcıya uygun sayfayı gösterir.

Sipariş Yönetimi ve Veritabanı Entegrasyonu

Wix platformunda sipariş bilgilerinin tutulması için Wix Data (veritabanı) kullanılmalıdır. Her ödeme işlemi için benzersiz bir sipariş numarası (Order ID) oluşturulmalı ve bu numara hem Garanti API'sine gönderilmeli hem de kendi veritabanınızda saklanmalıdır. Bu eşleştirme sayesinde callback verilerini doğru siparişle ilişkilendirebilirsiniz.

Sipariş durumları için bir enum yapısı oluşturmanız önerilir: beklemede, ödeme başlatıldı, 3D Secure'da, ödeme başarılı, ödeme başarısız gibi durumlar tanımlanabilir. Her aşamada sipariş durumu güncellenmelidir. Ayrıca tüm API yanıtları ve hata mesajları loglama amacıyla kaydedilmelidir. Bu loglar sorun giderimde hayati önem taşır.

Garanti BBVA'nın sağladığı Enpara.com Sanal POS Yönetim Paneli üzerinden işlemlerinizi takip edebilir, mutabakat yapabilir ve raporlama işlemlerini gerçekleştirebilirsiniz. Bu panel üzerinden test ve canlı ortam işlemlerinizi ayrı ayrı görebilirsiniz.

Test Süreci ve Hata Yönetimi

Canlıya geçmeden önce kapsamlı testler yapılması zorunludur. Garanti BBVA test kartları kullanılarak başarılı ödeme, yetersiz bakiye, hatalı kart bilgisi, 3D Secure hatası gibi farklı senaryolar test edilmelidir. Test kartı bilgileri Garanti'nin teknik dokümantasyonunda mevcuttur.

Her olası hata durumu için kullanıcı dostu mesajlar hazırlanmalıdır. Teknik hata kodları doğrudan kullanıcıya gösterilmemeli, bunun yerine anlaşılır açıklamalar sunulmalıdır. Örneğin "05 - İşlem onaylanmadı" hata kodu yerine "Bankanız işlemi onaylamadı. Lütfen bankanızla iletişime geçin veya farklı bir kart deneyin" gibi bir mesaj gösterilebilir.

Timeout durumları için retry mekanizması kurulmalıdır. Garanti API'sine yapılan isteklerde 30 saniye gibi bir timeout süresi belirlenmeli ve bu süre aşıldığında kullanıcı bilgilendirilmelidir. Ayrıca ağ hatalarında otomatik yeniden deneme sayısı sınırlandırılmalıdır.

Güvenlik ve Uyumluluk Gereksinimleri

PCI DSS (Payment Card Industry Data Security Standard) standartlarına uyum kritik öneme sahiptir. Kredi kartı bilgileri asla sunucunuzda saklanmamalı, loglanmamalı veya veritabanına yazılmamalıdır. Kart bilgileri doğrudan Garanti'nin sistemine iletilmelidir.

SSL sertifikası mutlaka kurulu olmalı ve tüm ödeme sayfaları HTTPS protokolü üzerinden sunulmalıdır. Wix otomatik olarak SSL sağlasa da, özel domain kullanıyorsanız sertifikanın aktif olduğundan emin olmalısınız.

KVKK (Kişisel Verilerin Korunması Kanunu) kapsamında müşteri bilgilerinin saklanması ve işlenmesi konusunda gerekli yasal metinler hazırlanmalıdır. Ödeme sayfasında gizlilik politikası ve kullanım şartları linklerinin bulunması zorunludur.

Performans Optimizasyonu ve Kullanıcı Deneyimi

Ödeme sayfasının hızlı yüklenmesi kullanıcı deneyimi açısından kritiktir. Velo fonksiyonlarınızı optimize ederek API yanıt sürelerini minimize etmelisiniz. Asenkron işlemler kullanarak sayfa donmalarını önleyebilirsiniz.

3D Secure sayfasına yönlendirme sırasında bir loading göstergesi eklenmelidir. Kullanıcı işlemin devam ettiğini görmeli ve beklemesi gerektiğini anlamalıdır. Callback sonrası sayfa yönlendirmelerinde smooth geçişler kullanılmalıdır.

Mobil uyumluluk testleri mutlaka yapılmalıdır. Wix responsive tasarım sunsa da, özellikle ödeme formlarının küçük ekranlarda düzgün çalıştığından emin olunmalıdır. 3D Secure sayfasının mobil cihazlarda popup blocker tarafından engellenme durumu test edilmelidir.

Dokümantasyon ve Destek Kaynakları

Teknik destek için Garanti BBVA'nın işyeri çözüm merkezi ile iletişime geçebilirsiniz. Ayrıca Wix Velo Dokümantasyonu (wix.com/velo/reference) HTTP istekleri, veritabanı işlemleri ve backend fonksiyonları hakkında detaylı bilgi sunar.

Entegrasyon sırasında karşılaşılan yaygın sorunlar ve çözümleri için Wix Community forumlarını ve Garanti BBVA'nın SSS (Sıkça Sorulan Sorular) bölümünü incelemeniz faydalı olacaktır. GitHub'da açık kaynak Garanti POS entegrasyon örnekleri de bulunmaktadır, ancak bunların güvenlik açısından dikkatle incelenmesi gerekir.

Bu entegrasyonun başarılı bir şekilde tamamlanması, işletmenizin profesyonel ve güvenilir bir ödeme altyapısına kavuşmasını sağlar. Düzenli bakım, güvenlik güncellemeleri ve performans izleme ile sistemin sürekliliği garanti altına alınmalıdır.