Yapı Kredi POS’u Wix Üzerine Kurma

Wix platformunda e-ticaret sitesi işleten işletmeler için Yapı Kredi Sanal POS entegrasyonu, Türkiye'nin köklü bankalarından birinin güvenilir ödeme altyapısını kullanma imkanı sunuyor. World kart ekosistemi, güçlü teknolojik altyapı ve geniş müşteri tabanıyla öne çıkan Yapı Kredi, e-ticaret işletmeleri için değerli bir ödeme çözümü sağlıyor.

Yapı Kredi Sanal POS Nedir?

Yapı Kredi Sanal POS, e-ticaret siteleri için geliştirilmiş kurumsal düzeyde bir online ödeme çözümüdür. Türkiye'nin en büyük özel bankalarından biri olan Yapı Kredi'nin teknolojik altyapısı, güvenilir ve hızlı ödeme deneyimi sunuyor.

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

Yapı Kredi Sanal POS'un temel özellikleri arasında 3D Secure 2.0 ile güçlendirilmiş işlem güvenliği, World kart programı avantajları ve puan sistemi, Visa, Mastercard, Troy ve American Express kart desteği, 2-12 ay arası esnek taksit seçenekleri, gelişmiş fraud koruma sistemleri, hızlı provizyon ve düşük işlem süresi ile 7/24 teknik destek hizmeti bulunuyor.

Yapı Kredi POS'un avantajları değerlendirildiğinde World kart müşteri tabanına erişim büyük fırsat sunuyor. Worldpuan entegrasyonu ile müşteri sadakati artırılabiliyor. Rekabetçi komisyon oranları maliyet avantajı sağlıyor. Modern ve geliştirici dostu API yapısı entegrasyonu kolaylaştırıyor. Kobi Kredi Kartı sahiplerine özel avantajlar bulunuyor.

Yapı Kredi Sanal POS Başvuru Süreci

Entegrasyon öncesinde Yapı Kredi'den 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 Yapı Kredi hesap bilgileri (mevcut müşteriler için avantaj).

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 Yapı Kredi ilişkisi bulunuyor.

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

Başvuru onayı sonrası alınacak bilgiler olarak Merchant ID (İşyeri Numarası), Terminal ID (Terminal Numarası), POSNET ID, Store Key (3D Secure Anahtarı), API kullanıcı bilgileri ve endpoint URL'leri sağlanır.

Entegrasyon İçin Gerekli API Bilgileri

Yapı Kredi'den 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 MerchantId (İşyeri Numarası), TerminalId (Terminal Numarası), PosnetId (POSNET tanımlama numarası), EncKey (3D Secure şifreleme anahtarı) ve API kullanıcı bilgileri 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 adresi, production ortamı için posnet.yapikredi.com.tr/PosnetWebService/XML adresi kullanılır. 3D Secure yönlendirmesi için test ortamında setmpos.ykb.com/3DSWebService/YKBPaymentService, production ortamında posnet.yapikredi.com.tr/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 YKB_MERCHANT_ID, YKB_TERMINAL_ID, YKB_POSNET_ID, YKB_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 yapikrediPOS.jsw adında bir dosya oluşturulur. Bu dosya ödeme başlatma fonksiyonu, XML request oluşturma fonksiyonu, MAC (Message Authentication Code) hesaplama fonksiyonu, Yapı Kredi 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. Yapı Kredi POSNET sistemi, işlem güvenliğini sağlamak için MAC 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.

Üçüncü aşama: 3D Secure yönlendirme yapılandırması için iki adet callback URL tanımlanır. Success URL (MerchantReturnURL) 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ı Yapı Kredi POSNET sistemi XML tabanlı iletişim kullanır. Ödeme başlatma (OOS - Online Ödeme Sistemi), 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 Yapı Kredi'den 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. Yapı Kredi'nin 3D Secure 2.0 altyapısı, gelişmiş güvenlik özellikleri ve World kart entegrasyonu 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. Gerekli MAC değerleri hesaplanır ve XML request hazırlanır. Müşteri Yapı Kredi 3D Secure sayfasına otomatik yönlendirilir. SMS kodu veya Yapı Kredi Mobil onayı ile işlem doğrulanır. Başarılı doğrulama sonrası banka callback URL'e işlem sonucunu POST eder. Backend gelen XML yanıtı parse eder ve MAC doğrulaması yapar. Provizyon işlemi tamamlanır ve sipariş onaylı statüsüne geçirilir. Müşteri başarılı ödeme sayfasına yönlendirilir.

POSNET yanıt kodları ve anlamları şöyledir: 1 değeri başarılı işlemi (Approved) ifade eder. 0 değeri başarısız işlemi gösterir. ApprovedCode başarılı işlemlerde provizyon kodunu içerir. HostLogKey işlem referans numarasıdır ve iade işlemlerinde kullanılır.

Taksit Yapılandırması ve World Avantajları

Yapı Kredi Sanal POS, kapsamlı taksit seçenekleri ve World kart programı avantajları sunuyor. World kart sahiplerine ö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 00 gönderilir. Taksitli işlemler için 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12 değerleri kullanılır.

World kart avantajları kapsamında World kart sahiplerine özel ek taksit imkanı sunuluyor. Worldpuan kazanımı ve harcama imkanı sağlanıyor. World Elite ve World Business özel kampanyaları mevcut. Chip-para entegrasyonu ile alternatif ödeme seçeneği bulunuyor.

BIN bazlı kampanya sorgulama için kart numarasının ilk 6 hanesi kullanılarak o karta uygulanabilecek kampanyalar sorgulanabilir. Bu sorgu, müşteriye özel tekliflerin gösterilmesini sağlar.

Kampanya entegrasyonu yapılırken Yapı Kredi POS panelinden tanımlanan kampanyalar API üzerinden sorgulanabilir. Karta özel indirimler ve ek taksitler otomatik uygulanır. Worldpuan ile ödeme seçeneği aktifleştirilebilir.

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 Yapı Kredi POSNET hata kodları ve açıklamaları şöyledir: 0 kodu başarısız işlemi, 1 kodu başarılı işlemi, 00 kodu onaylanan işlemi (provizyon kodu ile), 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, 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 fraud şüphesini, 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ı, 65 kodu günlük işlem adedinin aşıldığını ve 91 kodu bankadan yanıt alınamadığını 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, 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.

Yapı Kredi ek güvenlik özellikleri olarak OOS (Online Ödeme Sistemi) güvenlik altyapısı, işlem bazlı MAC doğrulaması, gelişmiş fraud detection sistemi, velocity check (hız kontrolü) mekanizması ve şüpheli işlem uyarı sistemi sunuluyor.

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

Entegrasyon tamamlandıktan sonra kapsamlı test süreci zorunludur. Yapı Kredi, 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 bilgileri Yapı Kredi 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, World kart ile ödeme, Worldpuan ile ödeme (aktifse), 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 Yapı Kredi 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 Yapı Kredi'nin 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 Yapı Kredi Sanal 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 Yapı Kredi 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.

Yapı Kredi POS panelinde izleme kapsamında günlük işlem özeti, taksit dağılımı raporu, kart tipi bazlı analiz (World, Visa, Mastercard), Worldpuan işlem raporu, 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 Yapı Kredi 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.

MAC doğrulama hatası için parametre sıralamasının POSNET dokümantasyonuna uygunluğu kontrol edilmeli, encoding (UTF-8) doğrulanmalı, tutar formatı kontrol edilmeli (YTL cinsinden, nokta veya virgül olmadan), EncKey değerinin doğruluğu teyit edilmeli ve hash algoritmasının SHA-256 olduğu doğrulanmalı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.

OOS kayıt hatası için MerchantId ve TerminalId doğruluğu kontrol edilmeli, PosnetId değerinin aktif olduğu teyit edilmeli, IP kısıtlaması varsa whitelist kontrolü yapılmalı ve işlem tutarının limitlere uygunluğu doğrulanmalıdır.

3D Secure yönlendirme sorunu için callback URL'lerin erişilebilirliği kontrol edilmeli, SSL sertifikası doğrulanmalı ve XID değerinin unique olduğu kontrol edilmelidir.

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

Yapı Kredi Sanal POS entegrasyonu, Wix e-ticaret sitenize Türkiye'nin köklü bankalarından birinin güvenilir ödeme altyapısını kazandırır. World kart ekosistemi, Worldpuan entegrasyonu, rekabetçi komisyon oranları ve güçlü teknolojik altyapı, 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.

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