Wix Ziraat Bankası Sanal POS Entegrasyonu

Wix platformunda e-ticaret sitesi işleten işletmeler için Ziraat Bankası Sanal POS entegrasyonu, Türkiye'nin en köklü ve güvenilir bankasının ödeme altyapısını kullanma imkanı sunuyor. Devlet bankası güvencesiyle ödeme almak isteyen işletmeler için bu entegrasyon, müşteri güvenini artırırken rekabetçi komisyon oranlarından faydalanma fırsatı sağlıyor.

Ziraat Bankası Sanal POS Nedir?

Ziraat Bankası Sanal POS, Türkiye'nin en eski ve en yaygın bankasının e-ticaret işletmeleri için sunduğu online ödeme çözümüdür. Devlet bankası statüsü, geniş müşteri tabanı ve güçlü altyapısı ile öne çıkan sistem, özellikle güven odaklı alışveriş yapan Türk tüketiciler için tercih sebebi 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 Ziraat Bankası'nın tüm özelliklerinden faydalanılabilir.

Ziraat Bankası Sanal POS'un temel özellikleri arasında devlet bankası güvencesi ve kurumsal güvenilirlik, 3D Secure 2.0 ile güçlendirilmiş işlem güvenliği, Visa, Mastercard, Troy kart desteği, esnek taksit seçenekleri ve kampanya yönetimi, rekabetçi komisyon oranları, geniş şube ağı ile yerinde destek imkanı ve 7/24 teknik destek hizmeti bulunuyor.

Ziraat Bankası POS'un avantajları değerlendirildiğinde Türkiye'nin en yaygın banka kartı kullanıcı tabanına erişim, devlet bankası algısının yarattığı güven etkisi, KOBİ'lere özel avantajlı komisyon oranları, tarım ve üretim sektörlerine özel kampanyalar ile yaygın ATM ve şube ağı desteği öne çıkıyor.

Ziraat Bankası Sanal POS Başvuru Süreci

Entegrasyon öncesinde Ziraat Bankası'ndan sanal POS başvurusu yapılması ve onaylanması gerekir. Başvuru süreci genellikle 7-14 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 bilgileri (Ziraat Bankası hesabı avantaj sağlar).

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 Ziraat Bankası ilişkisi bulunuyor.

Başvuru onayı sonrası alınacak bilgiler olarak Merchant ID (İşyeri Numarası), Terminal ID (Terminal Numarası), POSNET ID, 3D Secure Şifreleme Anahtarı (ENCKEY) ve API kullanıcı bilgileri sağlanır.

Entegrasyon İçin Gerekli API Bilgileri

Ziraat Bankası'ndan 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 Merchant ID (MID - İşyeri Numarası), Terminal ID (TID - Terminal Numarası), POSNET ID (POS tanımlama numarası), ENCKEY (3D Secure şifreleme anahtarı), API kullanıcı adı ve API ş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 setmpos.ykb.com/PosnetWebService/XML (test modu) adresi, production ortamı için www.posnet.ykb.com/PosnetWebService/XML adresi kullanılır. 3D Secure yönlendirmesi için test ortamında setmpos.ykb.com/3DSWebService/YKBPaymentService, production ortamında www.posnet.ykb.com/3DSWebService/YKBPaymentService 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 ZIRAAT_MERCHANT_ID, ZIRAAT_TERMINAL_ID, ZIRAAT_POSNET_ID, ZIRAAT_ENCKEY şeklinde.

Gerekli modüller ve paketler olarak wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data, crypto-js ve xml2js (XML işleme için) 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 ziraatPOS.jsw adında bir dosya oluşturulur. Bu dosya ödeme başlatma fonksiyonu, XML request oluşturma fonksiyonu, MAC (Message Authentication Code) hesaplama fonksiyonu, Ziraat API iletişim fonksiyonu, 3D Secure callback doğrulama fonksiyonu ve sipariş güncelleme fonksiyonunu içerir.

İkinci aşama: MAC hesaplama algoritması entegrasyonun en kritik bileşenidir. Ziraat Bankası, işlem güvenliğini sağlamak için MAC (Message Authentication Code) değeri gerektirir. MAC değeri oluşturma sıralaması MerchantID + TerminalID + Amount + Currency + InstallmentCount + XID + ENCKEY şeklindedir. Bu parametreler birleştirilerek SHA-256 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. 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: XML request yapısı Ziraat Bankası POSNET sistemi XML tabanlı iletişim kullanır. Ödeme başlatma, doğrulama ve iade işlemleri için standart XML şablonları hazırlanmalıdır.

Beşinci aşama: Callback endpoint oluşturma kapsamında Ziraat Bankası'ndan gelen yanıtları işleyecek HTTP fonksiyonları yazılır. Bu fonksiyonlar gelen XML verilerin parse edilmesini, MAC doğrulamasını, işlem sonucunun değerlendirilmesini ve sipariş durumunun güncellenmesini gerçekleştirir.

3D Secure Ödeme Akışı Detayları

3D Secure, online ödemelerde kart sahibi doğrulaması sağlayan güvenlik protokolüdür. Ziraat Bankası'nın 3D Secure 2.0 altyapısı, gelişmiş güvenlik özellikleri ve devlet bankası güvencesi 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 OOS (Online Ödeme Sistemi) kaydı oluşturur ve gerekli parametreleri hazırlar. Müşteri Ziraat Bankası 3D Secure sayfasına otomatik yönlendirilir. SMS kodu veya mobil bankacılık onayı ile işlem doğrulanır. Başarılı doğrulama sonrası Ziraat callback URL'e işlem sonucunu POST eder. Backend gelen XML yanıtı parse eder ve MAC doğrulaması 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 kodları ve anlamları şöyledir: 1 değeri başarılı doğrulamayı (Authenticated) ifade eder ve işlem onaylanmalıdır. 2 değeri kart sahibinin veya kartın sisteme kayıtlı olmadığını gösterir. 3 değeri doğrulama yapılamadığını belirtir. 4 değeri doğrulama denemesi yapıldığını gösterir. 5 değeri doğrulama başarısız olduğunu ifade eder. 0 değeri işlemin reddedildiğini gösterir.

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

Ziraat Bankası Sanal POS, kapsamlı taksit seçenekleri ve kampanya yönetimi imkanı sunuyor. Özellikle Bankkart ve Ziraat Bankası kartlarına özel avantajlar mevcuttur.

Taksit parametreleri olarak InstallmentCount parametresi taksit sayısını belirtir. Tek çekim için bu değer 00 veya boş gönderilir. Taksitli işlemler için 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12 değerleri kullanılır.

Ziraat Bankası kart avantajları kapsamında Bankkart sahiplerine özel ek taksit imkanı, Bankkart Combo ile puan kazanma, tarım kartlarına özel kampanyalar ve KOBİ kartlarına avantajlı komisyon oranları sunuluyor.

Kampanya entegrasyonu yapılırken Ziraat POS panelinden tanımlanan kampanyalar API üzerinden sorgulanabilir. Karta özel indirimler otomatik uygulanır. BIN bazlı kampanya kontrolü yapılabilir.

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 Ziraat Bankası hata kodları ve açıklamaları şöyledir: 0 kodu başarılı işlemi, 1 kodu banka tarafından reddedilen işlemi, 2 kodu şüpheli işlemi (bankayı arayın), 3 kodu geçersiz üye işyerini, 4 kodu karta el koyun uyarısını, 5 kodu onaylanmayan işlemi, 12 kodu geçersiz işlemi, 13 kodu geçersiz tutarı, 14 kodu geçersiz kart numarasını, 33 kodu süresi dolmuş kartı, 36 kodu kısıtlı 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, 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ı, 65 kodu günlük işlem adedinin aşıldığını, 75 kodu hatalı PIN 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, 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ı, MAC 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.

Ziraat Bankası ek güvenlik katmanları olarak OOS (Online Ödeme Sistemi) güvenlik altyapısı, işlem bazlı MAC doğrulaması, IP kısıtlama imkanı, günlük işlem limitleri ve şüpheli işlem uyarı sistemi sunuluyor.

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

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

Test ortamı bilgileri olarak test endpoint adresi setmpos.ykb.com üzerinden sağlanır. Test kart numaraları ve diğer test bilgileri Ziraat Bankası 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, 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 Ziraat 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ı - tranType: return), kısmi iade (işlem tutarının bir kısmı - tranType: return ile tutar belirtilerek) ve provizyon iptali (aynı gün içinde, gün sonu öncesi - tranType: void) bulunuyor.

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

Ziraat POS panelinde izleme kapsamında günlük işlem özeti, taksit dağılımı raporu, kart tipi bazlı analiz (Bankkart, Visa, Mastercard), 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 Ziraat POS panelinden ayarlanır. Günlük mutabakat raporu e-posta ile gönderilebilir. Haftalık hakediş ödemeleri takip edilebilir.

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.

MAC 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ş cinsinden), ENCKEY değerinin doğruluğu teyit edilmeli ve Base64 encoding doğru uygulanmalıdır.

XML parse hatası için XML yapısının POSNET şemasına uygunluğu kontrol edilmeli, özel karakterlerin escape edildiği doğrulanmalı, namespace tanımlamaları kontrol edilmeli ve encoding declaration eklenmelidir.

3D Secure yönlendirme sorunu için callback URL'lerin erişilebilirliği kontrol edilmeli, SSL sertifikası doğrulanmalı, OOS kaydının başarılı oluştuğu teyit edilmeli ve XID değerinin unique olduğu kontrol edilmelidir.

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

Ziraat Bankası Sanal POS entegrasyonu, Wix e-ticaret sitenize Türkiye'nin en güvenilir bankasının ödeme altyapısını kazandırır. Devlet bankası güvencesi, rekabetçi komisyon oranları ve geniş müşteri tabanına erişim, işletmelere önemli avantajlar sağlar. 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.

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