Wix'te Halkbank Sanal POS Entegrasyonu: KOBİ'ler İçin Güçlü Ödeme Altyapısı

Wix, Halkbank sanal POS entegrasyonunu destekleyerek işletmelere yerel bankayla güvenli ödeme alma imkanı sunuyor.

Halkbank'ın E-Ticaret Dünyasındaki Rolü

E-ticaret dünyasında başarılı olmak isteyen küçük ve orta ölçekli işletmeler için güvenilir bir ödeme altyapısı vazgeçilmezdir. Halkbank, Türkiye'nin köklü kamu bankalarından biri olarak, özellikle KOBİ'lere yönelik avantajlı komisyon oranları ve geniş müşteri tabanıyla dikkat çeker¹. Wix platformunda bir e-ticaret sitesi işletiyorsanız, Halkbank Sanal POS entegrasyonu hem maliyetleri düşürmek hem de müşteri güveni kazanmak açısından önemli bir adım olacaktır.

Halkbank'ın Sanal POS sistemi, fiziksel POS cihazlarının internet üzerinden kullanılan versiyonudur ve kartlara temas etmeden sadece doğru bilgiler girilerek ödeme yapılmasını sağlar². Bu sistemin en büyük avantajlarından biri raporlama ve takip kolaylığıdır. İşletmeler sipariş inceleme, işlem takibi ve satış istatistikleri gibi kayıtları kolaylıkla izleyebilir². Wix ile entegre edildiğinde ise bu avantajlar, platform

in kullanıcı dostu arayüzü ile birleşerek KOBİ'lere güçlü bir ödeme çözümü sunar.

Halkbank'ın KOBİ'lere Sunduğu Avantajlar

Halkbank, Türkiye'de KOBİ'lere destek veren öncü bankalardan biridir ve bu yönelim Sanal POS hizmetlerine de yansır. Bankanın 2024 yılı ücret tarifesine göre Sanal POS için yıllık aidat ücreti 175 TL'dir³. Peşin işlemler için komisyon oranı ise minimum %3,56 olarak belirlenmiştir³. Bu oranlar, özellikle yeni başlayan e-ticaret işletmeleri için oldukça rekabetçidir ve düşük işlem hacmine sahip firmaların ödeme altyapısı kurma maliyetlerini minimize eder.

Halkbank'ın bir diğer önemli avantajı, Türkiye genelindeki yaygın müşteri tabanıdır. Halkbank, özellikle kamu çalışanları, emekliler ve esnaflar arasında geniş bir kullanıcı kitlesine sahiptir. Müşterilerin ödeme yaparken Halkbank'ın tanıdık logosunu ve Paraf kart sistemini görmesi, güven faktörünü artırır ve alışverişi tamamlama oranlarını yükseltir⁴. Paraf, Halkbank'ın kredi kartı markasıdır ve Visa, MasterCard ile Troy logolu kartları destekler⁵. Müşteriler Paraf kartlarıyla yurt içinde ve yurt dışında alışveriş yapabilir, taksit avantajlarından yararlanabilir ve her harcamadan ParafPara puanı kazanabilir⁵.

Wix Entegrasyonunda 3D Secure: Güvenliğin Temel Taşı

Wix'te Halkbank Sanal POS entegrasyonunun en kritik bileşenlerinden biri 3D Secure sistemidir. 3D Secure, "three-domain secure" ifadesinin kısaltmasıdır ve ödeme sürecindeki üç temel aktörü temsil eder: kart sahibi, üye işyeri (merchant) ve kartı çıkaran banka (issuer)⁶. Bu sistem, online alışverişlerde kredi kartı ve banka kartı ödemelerinin güvenliğini artırmak için geliştirilmiş bir kimlik doğrulama protokolüdür.

Halkbank sisteminde 3D Secure, müşterinin kart bilgilerini girdikten sonra otomatik olarak devreye girer. Müşteri, bankasına ait doğrulama ekranına yönlendirilir ve cep telefonuna gönderilen tek kullanımlık SMS şifresini girer⁶. Bu şifre her işlem için benzersizdir ve sadece kart sahibinin cep telefonuna gönderilir. Dolayısıyla, kart bilgileri çalınmış olsa bile, bu tek kullanımlık şifre olmadan ödeme tamamlanamaz⁶.

Halkbank, 3D Secure sistemini farklı kart şemalarına göre özelleştirmiştir. Visa kartlar için "Visa Secure", MasterCard kartlar için "MasterCard SecureCode" ve Troy kartlar için "GO-Güvenli Öde" adı altında hizmet verir⁷. Paraf kart sahipleri, bankanın sistemine otomatik olarak kaydedildikleri için ek bir kayıt işlemine gerek duymaz⁷. İlk kullanımda sistem, kişiselleştirilmiş güvenlik mesajı olarak kullanıcının cep telefonu numarasının maskeli halini gösterir, ancak kullanıcı dilerse bu mesajı özelleştirebilir⁷.

Wix Velo Backend ile API Entegrasyonu

Wix platformunda Halkbank Sanal POS entegrasyonu, Wix Velo backend altyapısı kullanılarak gerçekleştirilir. Velo, Wix'in JavaScript tabanlı geliştirme ortamıdır ve API çağrıları, veritabanı işlemleri ve ödeme entegrasyonları gibi backend işlevlerini yönetmenizi sağlar. Halkbank entegrasyonu için ilk adım, bankanın API dokümantasyonunu incelemek ve gerekli kimlik bilgilerini toplamaktır.

Halkbank Sanal POS başvurunuz onaylandıktan sonra, banka size bir e-posta gönderir. Bu e-postada mağaza numaranız, kullanıcı adınız ve güvenlik kodunuz gibi temel bilgiler yer alır⁸. Ancak entegrasyon için bunlar yeterli değildir. Ayrıca Halkbank yönetim panelinize giriş yaparak bir "API Kullanıcısı" oluşturmanız gerekir⁹. Bu kullanıcı, Wix backend'inizin Halkbank sistemine erişmesini sağlar.

API Kullanıcısı Oluşturma

Halkbank yönetim paneline (genellikle https://sanalpos.halkbank.com.tr/halk/report/user.login adresinden) giriş yaptıktan sonra, sol menüden "Yönetim" sekmesine tıklayın¹⁰. Ardından "Yeni Kullanıcı Ekle" seçeneğini seçin ve açılan formda kullanıcı tipi olarak "API Kullanıcısı" seçin⁹. Kullanıcı adı ve şifre belirleyin - bu bilgileri Wix backend'inizde kullanacaksınız, dolayısıyla güvenli bir yerde saklamanız önemlidir.

API kullanıcısı oluşturduktan sonra, "3D Ayarları" bölümüne gidin ve 3D modelinizi kontrol edin⁹. Eğer model "3D PAY" değilse, Halkbank müşteri temsilcinizle iletişime geçerek modelinizi 3D PAY olarak değiştirmelisiniz⁹. 3D PAY modeli, Wix gibi platformlarla entegrasyon için en uygun modeldir çünkü ödeme akışını tamamen kontrol etmenizi sağlar.

3D Güvenlik Anahtarı ve Hash Algoritması

Halkbank entegrasyonunda güvenliğin bir diğer kritik unsuru "3D Güvenlik Anahtarı"dır. Bu anahtar, işlem verilerinin hash'lenmesinde kullanılır ve verinin yolda manipüle edilmediğini garanti eder. Halkbank yönetim panelinde "Güvenlik Anahtarı Değiştirme" bölümünden bu anahtarı görebilir veya değiştirebilirsiniz⁸. Bu anahtarı Wix backend'inizde güvenli bir şekilde saklamanız gerekir - en iyi uygulama, Wix Secrets Manager kullanmaktır.

Halkbank sistemi, PCI DSS 4.0 güvenlik standartlarına uyum sağlamak amacıyla hash algoritmasını güncellemiştir¹¹. 31 Ağustos 2024 tarihi itibariyle, eski hash algoritmalarından "hash ver3" olarak adlandırılan yeni algoritmaya geçiş zorunlu hale gelmiştir¹¹. Bu güncelleme, Halkbank'ın altyapısını sağlayan Payten (eski Asseco) firması tarafından uygulanmıştır ve EstV3Pos altyapısında SHA-512 hash algoritmasını kullanır¹².

Wix Velo backend'inizde hash hesaplama işlemi şu şekilde yapılabilir:

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

async function calculateHalkbankHash(orderId, amount, currency) {
  const securityKey = await getSecret('halkbank_security_key');
  
  // Hash ver3 için veri string'i oluştur
  const dataString = orderId + amount + currency + securityKey;
  
  // SHA-512 hash hesapla
  const hash = crypto
    .createHash('sha512')
    .update(dataString, 'utf8')
    .digest('base64');
    
  return hash;
}

Bu hash değeri, hem ödeme başlatırken Halkbank'a gönderilen istekte hem de callback aşamasında dönen verinin doğrulanmasında kullanılır. Hash eşleşmezse, verinin manipüle edildiği anlamına gelir ve işlem iptal edilmelidir.

Ödeme Akışının Teknik Detayları

Wix'te Halkbank Sanal POS entegrasyonunda ödeme akışı birkaç aşamadan oluşur. Her aşama, hem güvenlik hem de kullanıcı deneyimi açısından özenle tasarlanmalıdır.

Aşama 1: Ödeme Başlatma

Müşteri Wix mağazanızda ödeme sayfasına geldiğinde ve Halkbank'ı ödeme yöntemi olarak seçtiğinde, ilk adım ödeme isteğini başlatmaktır. Bu aşamada Wix backend'iniz şu bilgileri toplar:

Sipariş numarası (OrderId)
Ödeme tutarı (Amount)
Para birimi (Currency - genellikle 949 TRY için)
Müşteri bilgileri (ad, soyad, e-posta, telefon)
Kart bilgileri (numara, son kullanma tarihi, CVV)

Bu bilgilerle birlikte bir hash değeri hesaplanır ve Halkbank API'sine bir POST isteği gönderilir:

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

export async function initiateHalkbankPayment(orderData) {
  const merchantId = await getSecret('halkbank_merchant_id');
  const apiUsername = await getSecret('halkbank_api_username');
  const apiPassword = await getSecret('halkbank_api_password');
  
  const hash = await calculateHalkbankHash(
    orderData.orderId,
    orderData.amount,
    '949' // TRY
  );
  
  const requestData = {
    MerchantId: merchantId,
    OrderId: orderData.orderId,
    Amount: orderData.amount,
    Currency: '949',
    CardNumber: orderData.cardNumber,
    CardExpiry: orderData.cardExpiry,
    CVV: orderData.cvv,
    Hash: hash,
    ReturnUrl: 'https://yoursite.wixsite.com/
    _functions/halkbankCallback',
    Language: 'tr'
  };
  
  const response = await fetch(
    'https://sanalpos.halkbank.com.tr/api/payment/init',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${Buffer.from(
          `${apiUsername}:${apiPassword}`
        ).toString('base64')}`
      },
      body: JSON.stringify(requestData)
    }
  );
  
  return await response.json();
}

Aşama 2: 3D Secure Yönlendirme

Halkbank API'den dönen yanıt, müşterinin 3D Secure doğrulama ekranına yönlendirilmesi için gerekli bilgileri içerir. Bu genellikle bir HTML formu veya yönlendirme URL'i şeklindedir. Wix frontend'inizde bu yönlendirmeyi gerçekleştirmeniz gerekir.

// Frontend kod (Wix Editor'da page code olarak)
import { initiatePayment } from 'backend/halkbankPayment';

$w.onReady(function () {
  $w('#payButton').onClick(async () => {
    const orderData = collectOrderData();
    const response = await initiatePayment(orderData);
    
    if (response.status === 'redirect') {
      // 3D Secure ekranına yönlendir
      window.location.href = response.redirectUrl;
    }
  });
});

Müşteri Halkbank'ın 3D Secure ekranında cep telefonuna gelen SMS şifresini girer. Şifre doğruysa, banka müşteriyi sizin belirlediğiniz ReturnUrl adresine geri yönlendirir.

Aşama 3: Callback İşleme

Callback URL, Halkbank'tan dönen sonuçları işleyen backend endpoint'inizdir. Bu endpoint, işlem sonucunu alır, hash'i doğrular ve sipariş durumunu günceller.

// backend/halkbankCallback.jsw
import { ok, badRequest } from 'wix-http-functions';
import wixData from 'wix-data';

export async function post_halkbankCallback(request) {
  try {
    const formData = await request.body.formData();
    
    const orderId = formData.OrderId;
    const status = formData.Status;
    const hash = formData.Hash;
    const authCode = formData.AuthCode;
    const transId = formData.TransId;
    
    // Hash doğrulama
    const expectedHash = await calculateHalkbankHash(
      orderId,
      formData.Amount,
      formData.Currency
    );
    
    if (hash !== expectedHash) {
      console.error('Hash mismatch!');
      return badRequest({ 
        error: 'Invalid hash' 
      });
    }
    
    // Sipariş durumunu güncelle
    if (status === 'APPROVED') {
      await wixData.update('Orders', {
        _id: orderId,
        paymentStatus: 'paid',
        authorizationCode: authCode,
        transactionId: transId,
        paymentDate: new Date()
      });
      
      return ok({ 
        redirect: '/order-confirmation?id=' + orderId 
      });
    } else {
      return badRequest({ 
        error: 'Payment failed',
        message: formData.ErrorMessage 
      });
    }
  } catch (error) {
    console.error('Callback error:', error);
    return badRequest({ error: error.message });
  }
}

Taksit, İade ve İptal İşlemleri

Halkbank Sanal POS sistemi, tek çekim ödemenin yanı sıra taksitli satış, iade ve provizyon iptali gibi temel ödeme özelliklerini de destekler¹³. Bu özellikler, Wix entegrasyonu ile sorunsuz şekilde kullanılabilir ve işletmelere esnek ödeme yönetimi imkanı sunar.

Taksitli Satış

Taksit seçenekleri, müşterilerin yüksek tutarlı alışverişlerde ödemeyi bölerek yapmasına olanak tanır. Halkbank'ta taksit oranları, bankayla yapılan anlaşmaya göre belirlenir. Wix backend'inizde taksit seçeneklerini müşteriye sunmak için şu şekilde bir yapı kurabilirsiniz:

const installmentOptions = {
  '2': { rate: 0, fee: 0 },      // 2 taksit komisyonsuz
  '3': { rate: 1.5, fee: 1.5 },  // 3 taksit %1.5 komisyon
  '6': { rate: 3, fee: 3 },      // 6 taksit %3 komisyon
  '9': { rate: 4.5, fee: 4.5 },  // 9 taksit %4.5 komisyon
  '12': { rate: 6, fee: 6 }      // 12 taksit %6 komisyon
};

function calculateInstallmentAmount(amount, installment) {
  const option = installmentOptions[installment];
  if (!option) return amount;
  
  const feeAmount = amount * (option.rate / 100);
  return amount + feeAmount;
}

Ödeme başlatırken, müşterinin seçtiği taksit sayısını Halkbank API'sine iletirsiniz. Banka, kartın taksit yapabilme durumunu kontrol eder ve uygunsa işlemi taksitli olarak gerçekleştirir.

İade İşlemi

Müşteri ürünü iade etmek istediğinde, Wix backend'inizden Halkbank API'sine bir iade isteği gönderebilirsiniz. İade işlemi, orijinal işlemin transaction ID'si (TransId) kullanılarak yapılır:

async function refundPayment(transactionId, amount) {
  const merchantId = await getSecret('halkbank_merchant_id');
  const apiUsername = await getSecret('halkbank_api_username');
  const apiPassword = await getSecret('halkbank_api_password');
  
  const refundData = {
    MerchantId: merchantId,
    TransactionId: transactionId,
    RefundAmount: amount,
    RefundReason: 'Customer request'
  };
  
  const response = await fetch(
    'https://sanalpos.halkbank.com.tr/api/payment/refund',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${Buffer.from(
          `${apiUsername}:${apiPassword}`
        ).toString('base64')}`
      },
      body: JSON.stringify(refundData)
    }
  );
  
  const result = await response.json();
  return result.status === 'SUCCESS';
}

İade işlemleri genellikle 3-5 iş günü içinde müşterinin hesabına yansır. Kısmi iade de mümkündür - orijinal tutarın bir kısmını iade edebilirsiniz.

Provizyon İptali

Provizyon iptali, işlem aynı gün içinde iptal edildiğinde kullanılır. Normal iade işleminden farkı, müşterinin kartından hiç para çekilmemiş gibi işlem yapmasıdır. Bu, müşteri memnuniyeti açısından önemlidir çünkü müşteri iade beklemez:

async function voidTransaction(transactionId) {
  const merchantId = await getSecret('halkbank_merchant_id');
  
  const voidData = {
    MerchantId: merchantId,
    TransactionId: transactionId
  };
  
  const response = await fetch(
    'https://sanalpos.halkbank.com.tr/api/payment/void',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(voidData)
    }
  );
  
  const result = await response.json();
  return result.status === 'SUCCESS';
}

Provizyon iptali, genellikle işlem yapıldıktan sonraki 24 saat içinde mümkündür. Bu süre geçtikten sonra normal iade işlemi yapmanız gerekir.

IP Kısıtlaması ve Güvenlik Önlemleri

Halkbank Sanal POS sistemi, güvenlik amacıyla IP kısıtlaması uygular¹⁴. Bu, sadece önceden tanımlanmış IP adreslerinden gelen isteklerin kabul edildiği anlamına gelir. Wix sitenizdeki backend kodları Wix'in kendi sunucularında çalıştığı için, Wix'in sunucu IP'sini Halkbank'a bildirmeniz gerekir.

Ancak burada önemli bir nokta var: Wix, shared hosting altyapısı kullandığı için sabit bir IP adresi vermez. Bu durum, Halkbank gibi IP kısıtlaması uygulayan bankalarla entegrasyon yaparken zorluk çıkarabilir. Çözüm olarak iki yol izlenebilir:

Aracı API Servisi Kullanmak: Sabit IP'ye sahip bir VPS sunucu kiralayıp, Wix'ten bu sunucuya istek gönderin, sunucu da Halkbank'a ileterek yanıtı Wix'e döndürsün.
Halkbank'tan IP Kısıtlamasını Gevşetmek: Bazı durumlarda Halkbank, IP kısıtlamasını tamamen kaldırmayı veya geniş IP bloklarına izin vermeyi kabul edebilir. Müşteri temsilcinizle bu konuyu görüşmelisiniz.

Güvenlik açısından bir diğer önemli nokta, API kullanıcı adı ve şifrenizin korunmasıdır. Wix Secrets Manager kullanarak bu bilgileri güvenli bir şekilde saklayın ve asla frontend kodunda veya public olarak erişilebilir dosyalarda tutmayın.

Halkbank Yönetim Paneli ve Raporlama

Halkbank Sanal POS yönetim paneli, işletmelere kapsamlı raporlama ve işlem takibi imkanı sunar. Panel üzerinden tüm işlemleri görüntüleyebilir, tarih aralığına göre filtreleyebilir ve Excel formatında dışa aktarabilirsiniz.

Panel ana başlıkları şunlardır:

Raporlar: Günlük, haftalık veya aylık bazda satış raporları alabilirsiniz. Başarılı işlemler, başarısız işlemler, iade edilen işlemler gibi kategorilere göre filtreleme yapabilirsiniz.

İşlem Takibi: Her işlemin detaylarını görebilirsiniz - müşteri adı, tutar, kart son 4 hanesi, authorization kodu, işlem tarihi ve saati gibi bilgiler mevcuttur.

Mutabakat: Gün sonu mutabakatı yaparak, Wix sitenizde kayıtlı satışlarla Halkbank panelindeki işlemleri karşılaştırabilirsiniz. Bu, olası tutarsızlıkları tespit etmek için önemlidir.

Kullanıcı Yönetimi: Farklı yetki seviyeleriyle kullanıcılar oluşturabilirsiniz. Örneğin, muhasebe departmanına sadece rapor görüntüleme yetkisi verirken, yöneticiye iade ve iptal yetkisi verebilirsiniz.

Bildirimler: Belirli olaylar için (büyük tutarlı işlem, şüpheli işlem vb.) e-posta veya SMS bildirimi ayarlayabilirsiniz.

Türkiye Finans Sistemine Tam Uyum

Halkbank Sanal POS entegrasyonu, işletmenizin Türkiye finans sistemine tam uyumlu bir ödeme akışı kurmasını sağlar. Tüm işlemler Türk Lirası cinsinden yapılır, Türk bankacılık düzenlemelerine uygun raporlanır ve vergi mevzuatına göre kayıt altına alınır.

Halkbank, Bankalar Kanunu ve BDDK (Bankacılık Düzenleme ve Denetleme Kurumu) düzenlemelerine tam uyumludur¹⁵. İşletmeniz için bu, ödeme süreçlerinizin yasal gereklilikleri karşıladığı ve düzenleyici otoriteler tarafından denetlenebileceği anlamına gelir. Ayrıca, KVKK (Kişisel Verilerin Korunması Kanunu) çerçevesinde müşteri verilerinizin güvenliği de sağlanmış olur⁶.

3D Secure kullanımı, KVKK uyumluluğu açısından da önemlidir çünkü müşteriye işlem yapılmadan önce bildirim yapılır ve müşteri işlemi doğrudan kendisi onaylar⁶. Bu, "açık rıza" prensibine uygunluk sağlar.

Sonuç: KOBİ'ler İçin Güçlü Bir Seçim

Wix'te Halkbank Sanal POS entegrasyonu, özellikle küçük ve orta ölçekli işletmeler için güçlü bir ödeme altyapısı sunar. Düşük komisyon oranları, yaygın müşteri tabanı, güvenilir 3D Secure sistemi ve kapsamlı raporlama özellikleriyle Halkbank, KOBİ'lerin e-ticaret yolculuğunda yanlarında olan bir iş ortağı konumundadır.

Entegrasyon süreci teknik bilgi gerektirir ve Wix Velo ile backend geliştirme deneyimi önemlidir. Ancak doğru yapılandırıldığında, sistem sorunsuz çalışır ve işletmenize uzun vadede önemli değer katabilir. Hash ver3 güncellemesine uyum sağlamak, IP kısıtlaması konusunu çözmek ve API kullanıcı bilgilerini güvenli saklamak gibi teknik detaylara dikkat edilmelidir.

Halkbank Sanal POS, Türkiye finans sistemine tam uyumlu, güvenli ve maliyet etkin bir çözümdür. Wix platformunun esnekliğiyle birleştiğinde, KOBİ'lere profesyonel bir e-ticaret deneyimi sunmanın kapılarını açar.