Wix İş Bankası Sanal POS Bağlantı Süreci: Yapılandırmadan Yönetime Pratik Rehber

İş Bankası Sanal POS’un Wix’e bağlanmasıyla kullanıcılar bankanın güvenli ve hızlı ödeme sisteminden yararlanabiliyor.

Bağlantı Süreci Nasıl İşler?

İş Bankası Sanal POS'u Wix sitenize bağlamak, teknik olarak karmaşık görünse de aslında mantıklı adımlardan oluşan yapılandırılmış bir süreçtir. Bu yazıda, bankanın API bilgilerinin sisteme eklenmesinden başlayarak, müşterinizin ödeme yapma anına kadar tüm süreci adım adım inceleyeceğiz. Ayrıca bağlantı tamamlandıktan sonra ödeme hareketlerinizi nasıl takip edeceğinizi de göreceğiz.

İlk Adım: API Bilgilerinin Velo Backend'e Yapılandırılması

Wix ile İş Bankası arasındaki köprü, Velo backend sisteminde kurulan yapılandırma ile başlar. Velo, Wix'in JavaScript tabanlı geliştirme platformudur ve custom kod yazmanıza, API'lerle çalışmanıza olanak tanır¹. Bağlantı sürecinin temelini oluşturan bu yapılandırma aşamasında, bankanın size sağladığı çeşitli bilgileri sisteme güvenli bir şekilde entegre etmeniz gerekir.

Merchant Bilgilerinin Sisteme Eklenmesi

İş Bankası ile sözleşmeniz onaylandıktan sonra banka size bir dizi kimlik bilgisi gönderir. Bu bilgiler arasında Mağaza Numarası, Terminal Numarası, API Kullanıcı Adı ve API Şifresi bulunur². Bu bilgilerin her biri, ödeme işlemlerinin doğru şekilde yönlendirilmesi ve işletmenizin benzersiz bir şekilde tanımlanması için kritik öneme sahiptir.

Velo backend sisteminde bu bilgilerin saklanması için en güvenli yöntem, Wix Secrets Manager'ı kullanmaktır³. Secrets Manager, hassas verilerin şifrelenmiş bir şekilde saklanmasını sağlar ve bu bilgilerin browser tarafında görünmesini engeller. Örneğin, API şifrenizi kod içinde açık metin olarak yazmak yerine, Secrets Manager'a kaydeder ve backend kodunuzda şu şekilde çağırabilirsiniz:

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

export async function getIsbankAPIPassword() {
  const password = await getSecret("isbankAPIPassword");
  return password;
}

Bu yöntem, güvenlik açısından olmazsa olmaz bir uygulamadır³. Merchant bilgileriniz sisteme eklendikten sonra, her ödeme işlemi bu kimlik bilgileriyle doğrulanır ve İş Bankası'na bu bilgilerle bağlanılır.

Güvenlik Anahtarları ve Hash Doğrulama

İş Bankası Sanal POS sisteminde güvenlik katmanlarından biri, hash doğrulama mekanizmasıdır. Hash, temel olarak verilerinizin matematiksel bir parmak izini oluşturur ve bu sayede verinin değiştirilip değiştirilmediği anlaşılabilir⁴. İş Bankası, iki aşamalı bir hash yapısı kullanır.

İlk aşamada, provizyon şifreniz ve terminal numaranız birleştirilerek SHA1 algoritması ile hashlenir. Bu işlem sonucunda "hashedPassword" değeri elde edilir. İkinci aşamada ise işlem bilgileriniz bu hashedPassword ile birleştirilerek tekrar hashlenip nihai "HashData" oluşturulur⁴. Bu HashData değeri, her API isteğinizde bankanın size gönderdiği bilgileri doğrulamak için kullanılır.

Velo backend'inizde bu hash hesaplamalarını otomatik yapan fonksiyonlar yazmanız gerekir. Örnek bir implementasyon şu şekilde olabilir:

import crypto from 'crypto';

function generateHashData(password, terminalNo, transactionData) {
  // Adım 1: Hashed Password
  const hashedPassword = crypto
    .createHash('sha1')
    .update(password + terminalNo)
    .digest('hex');
  
  // Adım 2: Hash Data
  const hashData = crypto
    .createHash('sha1')
    .update(transactionData + hashedPassword)
    .digest('hex');
  
  return hashData;
}

Bu mekanizma sayesinde, sizden bankanın sunucularına giden her istek doğrulanır ve üçüncü tarafların sisteminize müdahale etmesi engellenir⁴.

3D Secure Dönüş URL'lerinin Yapılandırılması

3D Secure sürecinin en kritik noktalarından biri, müşteriniz bankada doğrulamayı tamamladıktan sonra tekrar sitenize yönlendirilmesidir. Bu yönlendirme için iki ayrı URL tanımlamanız gerekir: başarılı işlemler için success URL ve başarısız işlemler için fail URL⁵.

Wix Velo sisteminde bu URL'ler genellikle http-functions.js dosyası içinde tanımlanan endpoint'lerdir⁶. Örneğin:

Success URL: https://yourdomain.wixsite.com/
_functions/payment3DSuccess

Fail URL: https://yourdomain.wixsite.com/
_functions/payment3DFail

Bu URL'ler İş Bankası sistemine kaydedilir ve müşteri 3D doğrulamayı tamamladığında banka otomatik olarak kullanıcıyı ilgili URL'ye yönlendirir⁵. Velo backend'inizde bu endpoint'leri dinleyen fonksiyonlar yazarak, gelen verileri işleyebilir ve ödeme durumunu güncelleyebilirsiniz.

İkinci Adım: Müşteri Ödeme Sürecinde Otomatik Yönlendirme

Tüm yapılandırma tamamlandıktan sonra artık sistem müşterilerinizin ödeme yapmasına hazırdır. Süreç, müşterinizin sitenizde "Ödemeyi Tamamla" butonuna bastığı anda başlar.

Ödeme Başlatma ve PaymentInfo Oluşturma

Müşteri ödeme butonuna tıkladığında, frontend kodunuz backend'de tanımladığınız bir fonksiyonu çağırır. Bu fonksiyon, PaymentInfo adında bir obje oluşturur⁷. PaymentInfo objesi, ödeme tutarını, para birimini, sipariş numarasını ve müşteri bilgilerini içerir.

export async function initiatePayment(amount, orderId) {
  const paymentInfo = {
    amount: amount,
    currency: 'TRY',
    orderId: orderId,
    merchantId: await getSecret("isbankMerchantId"),
    // diğer gerekli bilgiler...
  };
  
  const payment = await createPayment(paymentInfo);
  return payment;
}

Bu fonksiyon çalıştığında, Wix sistemi bir Payment objesi oluşturur ve bu objenin içinde unique bir payment ID bulunur⁷. Bu ID, ödeme sürecinin geri kalan kısmında işlemi takip etmek için kullanılır.

3D Secure Ekranına Otomatik Yönlendirme

Payment objesi oluşturulduktan sonra, frontend kodunuz startPayment() fonksiyonunu çağırır⁷. Bu fonksiyon, müşterinizi otomatik olarak İş Bankası'nın 3D Secure doğrulama ekranına yönlendirir. Bu yönlendirme işlemi kullanıcı deneyimi açısından sorunsuz olacak şekilde tasarlanmıştır - müşteri genellikle bir popup window veya yeni bir tab içinde bankanın sayfasını görür.

İş Bankası'nın 3D Secure ekranında müşteriden, bankasının mobil uygulamasından onay vermesi veya SMS ile gelen tek kullanımlık şifreyi girmesi istenir⁸. Bu adım, kartın gerçek sahibinin işlemi onaylamasını sağlar ve sahtecilik riskini büyük ölçüde azaltır⁸.

Müşteri bu doğrulama adımını tamamladığında veya iptal ettiğinde, İş Bankası müşteriyi yapılandırma aşamasında tanımladığınız dönüş URL'lerine yönlendirir. Eğer doğrulama başarılı olduysa success URL'e, başarısız olduysa fail URL'e gönderilir⁵.

Üçüncü Adım: Callback URL Üzerinden Bilgi Alma ve Doğrulama

Müşteri bankadan sitenize geri döndüğünde, asıl kritik süreç başlar. İş Bankası, müşteriyi yönlendirirken bir dizi parametre ile birlikte gönderir. Bu parametreler arasında işlemin başarılı olup olmadığı, işlem numarası, onay kodu ve 3D doğrulama sonucu gibi bilgiler bulunur⁹.

Callback Endpoint'inde Veri İşleme

Velo backend'inizde tanımladığınız callback endpoint'i bu parametreleri yakalar. Örnek bir callback fonksiyonu şu şekilde olabilir:

import { ok, serverError } from 'wix-http-functions';

export async function post_payment3DSuccess(request) {
  try {
    const params = await request.body.text();
    const parsedData = parseIsbankResponse(params);
    
    // Doğrulama işlemleri...
    const isValid = await validatePayment(parsedData);
    
    if (isValid) {
      await updateOrderStatus(
        parsedData.orderId, 
        'paid'
      );
      return ok({ redirect: '/order-success' });
    }
  } catch (error) {
    return serverError({ error: error.message });
  }
}

Burada dikkat edilmesi gereken ilk nokta, gelen verilerin doğrulanmasıdır. İş Bankası'ndan gelen yanıtın gerçekten bankadan geldiğini ve yolda değiştirilmediğini doğrulamak için hash kontrolü yapmanız kritik önem taşır⁴.

Ödeme Doğrulama Mekanizması

Doğrulama sürecinde birkaç kontrolden geçmeniz gerekir. İlk olarak, gelen hash değerini kendi hesapladığınız hash ile karşılaştırırsınız. Eğer iki değer eşleşiyorsa, verinin manipüle edilmediğinden emin olabilirsiniz⁴.

İkinci kontrol, mdStatus parametresinin değeridir. mdStatus=1 ise 3D doğrulama başarılıdır ve işleme devam edilebilir. mdStatus=0, 2, 3 veya 4 ise doğrulama başarısızdır ve işlem sonlandırılmalıdır¹⁰. Bu kontroller olmadan ödeme sürecine devam etmek ciddi güvenlik riskleri yaratır.

Üçüncü kontrol ise işlem tutarının doğruluğudur. Gelen işlem tutarının, başlangıçta gönderdiğiniz tutar ile aynı olduğundan emin olmalısınız. Bu kontrol, man-in-the-middle saldırılarına karşı koruma sağlar.

Sipariş Durumunun Güncellenmesi

Tüm doğrulama kontrolleri başarılı olduktan sonra, Wix sipariş sisteminizde ilgili siparişin durumunu güncellemeniz gerekir. Wix eCommerce API'sini kullanarak sipariş durumunu "pending" (beklemede) durumundan "paid" (ödendi) durumuna geçirebilirsiniz¹¹.

import { orders } from 'wix-stores-backend';

async function updateOrderStatus(orderId, status) {
  await orders.updateOrder(orderId, {
    paymentStatus: status,
    fulfillmentStatus: status === 'paid' 
      ? 'readyToShip' 
      : 'pending'
  });
}

Bu güncelleme sonrasında müşterinize otomatik olarak sipariş onay e-postası gönderilir ve işletme tarafında sipariş işleme süreci başlar¹¹.

Dördüncü Adım: Çift Panel Üzerinden Takip ve Yönetim

Bağlantı işlemi tamamlandıktan sonra, ödeme hareketlerinizi iki ayrı panel üzerinden takip edebilirsiniz. Bu çift panel yaklaşımı hem güvenlik hem de şeffaflık açısından önemli avantajlar sunar.

Wix Panelinden İşlem Takibi

Wix Dashboard'unuzda "Orders" bölümünden tüm siparişlerinizi ve ödeme durumlarını görebilirsiniz¹¹. Her sipariş kartında ödeme yöntemi, işlem durumu, tutarı ve tarih bilgisi bulunur. Ayrıca müşteri bilgilerini, sipariş içeriğini ve teslimat durumunu da aynı ekranda görebilirsiniz.

Wix panelinin avantajı, tüm e-ticaret operasyonlarınızı tek bir yerden yönetebilmenizdir. Sipariş, stok, müşteri yönetimi ve ödeme takibi aynı arayüz içinde entegre bir şekilde çalışır. Detaylı satış raporları, en çok satan ürünler, müşteri analizi gibi iş zekası özelliklerine de erişebilirsiniz¹¹.

İş Bankası POS Panelinden Detaylı Raporlama

İş Bankası Sanal POS yönetim paneline https://spos.isbank.com.tr adresinden giriş yapabilirsiniz¹². Bu panelde ödeme işlemlerinizin daha teknik ve finansal detaylarına ulaşırsınız.

Panel üzerinde her işlemin provizyon numarasını, işlem zamanını, kartın ilk 6 ve son 4 hanesini, taksit bilgilerini ve komisyon tutarlarını görebilirsiniz¹². Ayrıca günlük, haftalık ve aylık bazda toplam ciro raporlarına da erişebilirsiniz.

İş Bankası panelinin sunduğu önemli özelliklerden biri, manuel müdahale yapabilme yeteneğidir. Örneğin bir müşteri ürünü iade etmek istediğinde, bu panelden doğrudan iade işlemini başlatabilirsiniz. İptal işlemleri, ön provizyon kapama ve güvenlik anahtarı yönetimi gibi operasyonları da bu panel üzerinden gerçekleştirirsiniz¹².

İki Panelin Birlikte Kullanımı

Pratikte, günlük operasyonlarınızı genellikle Wix panelinden yürütürsünüz. Sipariş geldiğinde Wix'te görür, paketler ve gönderirsiniz. Ancak finansal mutabakat, komisyon hesaplamaları ve banka ile ilgili teknik konularda İş Bankası paneline başvurursunuz.

Örneğin, ay sonu geldiğinde toplam cirosunu kontrol etmek istediğinizde her iki paneli de kullanarak çapraz doğrulama yapabilirsiniz. Wix panelinde gördüğünüz sipariş sayısı ile İş Bankası panelinde gördüğünüz işlem sayısı eşleşmelidir¹¹,¹². Eğer bir tutarsızlık varsa, hemen fark edip araştırabilirsiniz.

Güvenlik ve Şeffaflık Avantajı

Çift panel yapısının en büyük avantajlarından biri, güvenlik ve şeffaflıktır. Her işlem her iki sistemde de kayıt altına alınır. Bu sayede herhangi bir anormallik durumunda iki ayrı log sistemi üzerinden inceleme yapabilirsiniz⁶.

Örneğin, bir müşteri "ödeme yaptım ama sipariş oluşmadı" dediğinde, İş Bankası panelinden ödemenin gerçekten gelip gelmediğini kontrol edebilirsiniz. Eğer ödeme gelmiş ama Wix'te sipariş oluşmamışsa, bu callback sürecinde bir sorun olduğunu gösterir ve teknik ekibiniz sorunu hızlıca çözebilir.

Aynı şekilde, "sipariş verdim ama param çekilmedi" şikayetinde Wix panelinden siparişin durumunu, İş Bankası panelinden de provizyon durumunu kontrol ederek gerçek durumu tespit edebilirsiniz¹².

Sorunsuz ve Yönetilebilir Ödeme Akışı

Wix ile İş Bankası Sanal POS bağlantısı, doğru yapılandırıldığında hem güvenli hem de yönetimi kolay bir ödeme sistemi sunar. API bilgilerinin Velo backend'e güvenli şekilde eklenmesi, hash doğrulama mekanizmalarının kurulması ve callback sürecinin doğru implementasyonu sürecin temelini oluşturur.

Müşteri deneyimi açısından süreç otomatik ve akıcıdır - müşteri kartını girer, bankasında doğrular ve işlem tamamlanır. Arka planda ise sağlam doğrulama mekanizmaları çalışır ve her adım hem Wix hem de İş Bankası sistemlerinde kayıt altına alınır.

İşletme sahipleri için ise çift panel avantajı, operasyonel ve finansal kontrolü bir arada sağlar. Günlük satış takibinden aylık ciro raporlarına, manuel iade işlemlerinden komisyon hesaplamalarına kadar tüm süreçler bu iki panel üzerinden yönetilebilir hale gelir.

Sonuç olarak, teknik detayları doğru uygulayan ve her iki paneli de aktif kullanan işletmeler için Wix-İş Bankası entegrasyonu güvenilir, şeffaf ve verimli bir ödeme altyapısı oluşturur.