Wix İş Bankası Sanal POS Teknik Entegrasyonu: Backend'den Yönetime Kapsamlı Rehber

Wix İş Bankası ödeme entegrasyonu sayesinde taksit, 3D Secure ve iade işlemleri sorunsuz şekilde yönetilebiliyor.

Hızlı Başlangıç: Bu Yazı Kimlere Yönelik?

E-ticaret sitesi sahipleri, geliştiriciler ve teknik detayları merak edenler için hazırlandı. Wix ile İş Bankası Sanal POS'un nasıl entegre edildiğini, backend yapısını ve ödeme süreçlerini adım adım açıklayacağız.

Önemli: Bu yazı, önceki "Wix İş Bankası Sanal POS Entegrasyonu" yazısının devamı niteliğinde olup, daha teknik detaylara odaklanıyor.

Entegrasyon Mimarisi: Nasıl Çalışır?

1. Wix Velo Backend Altyapısı

Velo Nedir? Wix'in JavaScript tabanlı geliştirme platformu. Özel kod yazmanıza, API'lerle çalışmanıza ve backend işlemleri yapmanıza olanak tanır¹.

Temel Özellikler:

Frontend ve backend kod yazabilme²
HTTP fonksiyonları
API anahtarlarını güvenli saklama
REST API desteği¹

Dev Mode Aktivasyonu:

Wix Editor'ü açın
Üst menüden "Dev Mode" seçin
"Turn on Dev Mode" tıklayın
Code Panel açılır²

2. Ödeme Akışı: Üç Kritik Endpoint

Wix İş Bankası entegrasyonunda üç temel endpoint kullanılır³:

A. Ödeme Başlangıç Endpoint'i

Görev: Ödeme sürecini başlatır

Süreç:

Müşteri "Ödeme Yap" butonuna tıklar
↓
Frontend event handler backend fonksiyonu çağırır
↓
Backend'de PaymentInfo objesi oluşturulur
↓
createPayment() fonksiyonu çalışır
↓
Payment objesi frontend'e döner⁴

Yapılan İşlemler:

Sipariş bilgilerini toplar
Ödeme tutarını hesaplar
İş Bankası'na gönderilecek parametreleri hazırlar
Unique transaction ID oluşturur⁵

B. 3D Secure Doğrulama Endpoint'i

Görev: Banka doğrulama ekranı ile entegrasyon

İşleyiş Şeması:

createPayment() sonrası
↓
startPayment() fonksiyonu çağrılır
↓
Müşteri bankaya yönlendirilir
↓
3D Secure şifresi girilir
↓
Banka doğrulama sonucunu döner⁴

Kritik Parametreler⁶:

ECI (Electronic Commerce Indicator)
CAVV (Cardholder Authentication Verification Value)
mdStatus (3D doğrulama durumu)
PARes (Payment Authentication Response)

mdStatus Değerleri:

1 = Başarılı doğrulama → Ödeme devam eder
0,2,3,4 = Başarısız → İşlem sonlandırılır⁶

C. Callback (Geri Bildirim) Endpoint'i

Görev: Banka'dan gelen sonuçları işler

Callback URL Yapısı:

https://<hesap-adı>.wixsite.com/
<site-adı>/_functions/paymentCallback

Webhook Sistemi⁷: Wix, ödeme durumu güncellemelerini almak için HTTP endpoint kullanır.

Gelen Veriler:

İşlem durumu (başarılı/başarısız)
Transaction ID
Hata kodları (varsa)
Provizyon numarası
Ödeme tutarı ve para birimi⁷

Callback İşleme Adımları³:

Webhook'u doğrula (digest header kontrolü)
Gelen verileri parse et
Wix sipariş sistemine aktar
Müşteriye bildirim gönder
HTTP 200 dönüş yap⁷

3. Velo ile Payment Provider Integration

Payment Provider Service Plugin⁸: Wix'te desteklenmeyen ödeme sağlayıcılarını entegre etmek için özel bir eklenti sistemi.

Kurulum Aşamaları⁸:

Dev Mode'u aç
Service Plugins bölümüne git
"Payment" seçeneğini ekle
İsim gir (boşluk ve özel karakter yok)
Kod dosyaları otomatik oluşturulur

Oluşturulan Dosyalar:

payment-provider.config.json (yapılandırma)
payment-provider.js (ana kod)

Parametre İşleme: İş Bankası Spesifik Detaylar

Hash Data Oluşturma

İş Bankası, güvenlik için iki parçalı HASH yapısı kullanır⁹:

Adım 1: Hashed Password

SHA1(provizyon_şifresi + terminal_numarası)
= hashedPassword

Adım 2: İşlem Hash'i

SHA1(işlem_bilgileri + hashedPassword)
= HashData

Bu HashData, her istekte <HashData> etiketi içinde gönderilir⁹.

Transaction ID Yönetimi

Kritik Kural: Her işlem unique bir TransactionID içermeli⁵.

Kullanım Alanları:

İşlem sorgulama
İptal işlemleri
İade işlemleri
Ön provizyon kapama⁵

İş Bankası Parametreleri

Zorunlu Alanlar:

Mağaza No
Terminal No
API Kullanıcısı
API Şifresi
3D Güvenlik Anahtarı
İşlem Tutarı (kuruş cinsinden)
Para Birimi (ISO 4217 kodu)
Taksit Sayısı¹⁰

Örnek:

12.34 TL → 1234 olarak gönderilir¹⁰
Peşin işlem → 00
2 taksit → 02¹⁰

Ödeme Sonrası İşlemler: İptal, İade, Provizyon

1. İptal (Cancel) İşlemi

Ne Zaman Kullanılır: Gün sonu mutabakatı gerçekleşmeden önce¹¹.

Özellikler:

Aynı gün içinde yapılmalı
Kart ekstresinde görünmez
Müşteri hesabına yansımaz¹¹

API Parametreleri:

İşlem Tipi: VOID
TransactionID: Orijinal işlem numarası
Tutar: İptal edilecek miktar

Dikkat: İptali iptal edilemez! Yanlışlıkla iptal edilirse işlem tekrar yapılmalı¹¹.

2. İade (Refund) İşlemi

Ne Zaman Kullanılır: Gün sonu mutabakatı geçtikten sonra¹¹.

Süreç:

İşlem 2-7 iş günü içinde müşteri kartına yansır¹²
Kart ekstresinde görünür
Tam veya kısmi iade yapılabilir¹³

API Çağrısı:

İşlem Tipi: REFUND
TransactionID: Orijinal işlem numarası
Tutar: İade edilecek miktar (opsiyonel)
Para Birimi: TRY, EUR, USD vb.

Önemli: İade edilecek tutar KDV dahil olmalı¹³.

3. Ön Provizyon İşlemleri

Ön Provizyon (Pre-Auth)

Kullanım Alanları:

Otel rezervasyonları
Araç kiralama
Yüksek tutarlı işlemler¹⁴

İşleyiş:

Auth İşlemi → Karta bloke koyulur
↓ (3-75 gün içinde)
Capture → Tutar çekilir
veya
Cancel → Bloke kaldırılır¹⁴

Post-Authorization (Ön Provizyon Kapama)

API İşlemi:

İşlem Tipi: POSTAUTH/CAPTURE
HostLogKey: Ön provizyon ID'si
Tutar: Çekilecek miktar

Özel Durum: Capture tutarı, ön provizyondan yüksek olamaz¹⁴.

4. Reversal (Teknik İptal)

Ne Zaman Gerekir: POS'tan cevap alınamadığında⁶.

Amaç: Askıda kalan işlemi geri almak.

Kullanım: Sadece finansal işlemlerin teknik iptali için⁶.

Wix Sipariş Sistemi Entegrasyonu

Order Management API

Wix'in eCommerce API sipariş yönetimi sağlar¹⁵.

Yetenekler:

Sepet yönetimi
Checkout süreci
Sipariş takibi
Ödeme durumu güncelleme¹⁵

Ödeme-Sipariş Senkronizasyonu³:

Callback gelir
↓
Ödeme durumu parse edilir
↓
Order Status API çağrılır
↓
Sipariş durumu güncellenir
(Pending → Paid / Failed)

Durum Kodları Eşleştirmesi

Banka → Wix Mapping:

İş Bankası Kodu	Wix Sipariş Durumu	Açıklama
00	Paid	Başarılı
01-99	Failed	Reddedildi³
3030	Canceled	Müşteri vazgeçti³
Pending	Pending	Doğrulama bekliyor³

Reason Codes³

Wix, ödeme durumlarını belirtmek için reason code'lar kullanır.

Örnekler:

5001 → Genel ret
5002 → Yetersiz bakiye
5003 → Geçersiz kart
3030 → Müşteri tarafından iptal³

Çift Panel Yönetimi: İşletme Avantajları

1. Wix Panelinden Yönetim

Erişilebilir Özellikler:

Sipariş listesi ve detayları
Ödeme durumları
İade talepleri
Müşteri bilgileri
Satış raporları¹⁵

Dashboard Widgets:

Günlük/aylık satış grafikleri
En çok satan ürünler
Başarısız ödeme oranları

2. İş Bankası Sanal POS Paneli

https://spos.isbank.com.tr/
isbank/report/user.login

Yapılabilecek İşlemler:

Provizyon işlemleri görüntüleme
İptal/iade manuel başlatma
Günsonu raporları
API kullanıcı yönetimi
3D ayarları kontrol¹⁶

Özel Raporlar:

Transaction bazlı detaylar
Komisyon hesaplamaları
Taksit dağılımı
Başarı/başarısızlık oranları

3. Çift Panel Avantajları

Güvenlik:

İki ayrı log sistemi
Cross-check imkanı
Fraud detection kolaylığı

Şeffaflık:

Her işlem her iki tarafta görünür
Tutarsızlıklar anında fark edilir
Mutabakat kolaylaşır

Esneklik:

Wix'ten otomatik
İş Bankası'ndan manuel
İhtiyaca göre seçim yapılabilir

Güvenlik Önlemleri

1. Secrets Manager²

Hassas Verilerin Saklanması:

import { getSecret } from 'wix-secrets-backend';

export async function getAPIKey() {
  const key = await getSecret("isbankAPIKey");
  return key;
}

Neden Önemli: API anahtarları browser'da görünmez².

2. HTTPS ve SSL

Zorunluluk:

Tüm istekler HTTPS üzerinden
Minimum 128-bit SSL⁵
Certificate geçerliliği kontrolü

3. Digest Header Validation³

Webhook Güvenliği:

const digestHeader = request.headers['Digest'];
const isValid = validateJWT(digestHeader);

if (!isValid) {
  return { status: 401 };
}

Bu, webhook'ların gerçekten Wix/İş Bankası'ndan geldiğini doğrular³.

4. PCI-DSS Uyumluluk

İş Bankası Garantisi: Tüm işlemler PCI-DSS Level 1 sertifikalı sistemlerden geçer¹⁷.

Bu Demektir Ki:

Kart verileri şifrelenir
Güvenli veri saklama
Düzenli güvenlik testleri
Fraud detection algoritmaları¹⁷

Test ve Canlıya Alma

Test Ortamı Kurulumu

İş Bankası Test Endpoint'leri:

Test API: https://sanalpostest.isbank.com.tr/
fim/api

Test 3D Gateway: https://sanalpostest.
isbank.com.tr/fim/est3Dgate

Test Kartları: Banka tarafından sağlanır (ör: 5440231234567890)

Entegrasyon Test Checklist

✅ Temel İşlemler:

[ ] Peşin satış (başarılı)
[ ] Peşin satış (başarısız - yetersiz bakiye)
[ ] Taksitli satış
[ ] 3D Secure doğrulama
[ ] 3D Secure vazgeçme

✅ İptal/İade:

[ ] Aynı gün iptal
[ ] Ertesi gün iade
[ ] Kısmi iade
[ ] Taksitli işlem iadesi

✅ Ön Provizyon:

[ ] Auth işlemi
[ ] Capture işlemi
[ ] Cancel işlemi

✅ Hata Senaryoları:

[ ] Timeout handling
[ ] Network kesintisi
[ ] Invalid response
[ ] Webhook retry

Canlıya Alma Prosedürü

1. Endpoint Değişikliği:

const PRODUCTION_API = 
  "https://spos.isbank.com.tr/fim/api";
const PRODUCTION_3D = 
  "https://spos.isbank.com.tr/fim/est3Dgate";

2. Credential Güncelleme:

Test API anahtarlarını kaldır
Production anahtarları Secrets Manager'a ekle
3D_PAY modelini doğrula¹⁶

3. Son Kontroller:

SSL sertifikası aktif mi?
Callback URL doğru mu?
Hata yakalama çalışıyor mu?
Log sistemi aktif mi?

Performans Optimizasyonu

1. Caching Stratejileri

Transaction State Cache:

// Sık sorgulanan işlemleri cache'le
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 dakika

Ne Cache'lenmeli:

Taksit oranları (günde 1 kez güncelle)
Kart BIN bilgileri
Banka son durum sorguları

2. Asenkron İşlemler

Webhook Processing:

export async function paymentCallback(request) {
  // Hızlı doğrulama
  const isValid = validateDigest(request);
  
  // HTTP 200 hemen dön
  wixData.insert("pendingWebhooks", request.body);
  
  return { status: 200 };
}

// Arka planda işle
async function processWebhook() {
  const pending = await wixData.query(
    "pendingWebhooks"
  ).find();
  
  for (const webhook of pending.items) {
    await updateOrder(webhook);
    await wixData.remove("pendingWebhooks", 
      webhook._id);
  }
}

3. Rate Limiting

API Çağrı Limitleri:

İş Bankası: 100 istek/dakika
Wix webhook: Retry logic (1s, 5s, 30s)⁷

Öneriler:

Batch işlemlerde delay ekle
Exponential backoff kullan
Circuit breaker pattern uygula

Sık Karşılaşılan Teknik Sorunlar

Problem: Webhook Alınamıyor

Çözümler:

Firewall kurallarını kontrol edin
HTTPS sertifikası geçerli mi?
Callback URL doğru yazıldı mı?
Log'larda istek var mı?

Test:

curl -X POST https://site-adi.wixsite.com/
_functions/callback -H "Content-Type: 
application/json" -d '{"test": true}'

Problem: 3D_PAY Hatası

Sebep: 3D model tipi yanlış¹⁶

Çözüm: İş Bankası panelinde:

Yönetim → 3D Ayarları → 
Model: "3D_PAY" olmalı

Problem: Transaction ID Collision

Sebep: Aynı ID ile birden fazla istek

Çözüm:

function generateUniqueTransactionID() {
  return `WIX_${Date.now()}_${
    Math.random().toString(36).substr(2, 9)
  }`;
}

Problem: Timeout (Zaman Aşımı)

İş Bankası Timeout: 30 saniye

Çözümler:

İstek öncesi veri hazırla
Reversal mekanizması kur⁶
Retry policy belirle

Gelecek: Wix SDK Geçişi

Önemli Bilgi: Wix, Velo API'lerinden Wix JavaScript SDK'ya geçiş yapıyor¹⁵.

Ne Değişecek:

Daha modern API yapısı
Blocks ile uygulama geliştirme
Daha iyi dokümantasyon

Geçiş Süreci:

Velo API'ler çalışmaya devam edecek
Yavaş geçiş önerilir
Yeni projeler SDK kullanmalı¹⁵

Sonuç ve Öneriler

Teknik Başarı İçin:

✓ Endpoint yapısını doğru kur ✓ Callback'leri güvenli işle ✓ Hata yönetimini sağlam yap ✓ Test coverage %100'e yaklaştır ✓ Monitoring ve logging aktif tut

İşletme Başarı İçin:

✓ Her iki paneli düzenli kontrol et ✓ Müşteri deneyimini önceliklendir ✓ Ödeme başarı oranını izle ✓ İade süreçlerini optimize et ✓ Güvenlik güncellemelerini takip et

Son Tavsiye: Entegrasyonu profesyonel bir ekibe yaptırın veya deneyimli bir Wix Partner ile çalışın. Ödeme sistemleri kritik altyapılardır ve en küçük hata bile büyük kayıplara neden olabilir.