Halkbank WooCommerce sanal POS entegrasyonu

Bir bakışta

Altyapı

NestPay (Asseco EST). Halkbank, Akbank, İş Bankası ve Ziraat ile aynı protokol.

Ödeme akışı

Kart bilgisi mağazanızdaki formda alınır, müşteri Halkbank’ın 3D Secure ekranına gider, dönüşte provizyon sunucudan alınır (3D Model).

Taksit

Var. Oranları POS hesabının “Taksit Oranları” tablosuna kendiniz girersiniz; BDDK sınırları otomatik uygulanır.

Saklı kart / abonelik

Yok. NestPay kart saklama sunmuyor; bunun için iyzico ya da PayTR kullanılır.

Gereken plan

Pro (₺3.500/yıl, KDV dahil) ya da üstü.

Halkbank’tan sanal POS almak

Sanal POS sözleşmesini şirketiniz adına doğrudan Halkbank’la yaparsınız; Invum POS bu sürecin tarafı değildir. Başvuru kanalı ve güncel koşullar Halkbank’ın Sanal POS sayfasında yer alıyor. Komisyon, blokaj süresi ve ücretler işletmeye göre değiştiği için bunları başvuru sırasında bankanızla netleştirin.

Başvurudan önce sitenizin hazır olması işi hızlandırır. Bankalar genellikle şunlara bakar: ürünlerin fiyatlarıyla birlikte yayında olması, SSL sertifikası, mesafeli satış sözleşmesi ve iade koşulları, şirket unvanı, adres ve iletişim bilgileri. Başvuruda Halkbank’a, sanal POS’u 3D Secure ile ve NestPay (EST) entegrasyonu üzerinden kullanacağınızı belirtin.

Halkbank’tan alacağınız bilgiler

Onaydan sonra Halkbank size sanal POS yönetim paneline giriş bilgisi ve entegrasyon bilgilerini verir. Invum POS’ta dört alan doldurulur. Alan adları eklenti ekranında İngilizce görünür:

API kullanıcısını panel girişinde kullandığınız yönetici hesabıyla karıştırmayın. NestPay panellerinde API işlemleri için ayrı bir kullanıcı tanımlanır; elinizde yoksa Halkbank’tan isteyin.

Invum POS’ta adım adım kurulum

1. Pro planı satın alın. Eklentiyi Hesabım › İndirmeler’den kurun, lisans anahtarını aktivasyon rehberindeki gibi etkinleştirin. WordPress.org’daki ücretsiz Lite kuruluysa ayarlarınız korunur.
2. WordPress yönetiminde Invum POS › POS Hesapları ekranını açıp Yeni POS Hesabı Ekle‘ye tıklayın.
3. Sağlayıcı listesinden NestPay – Halkbank‘ı seçin. Hesap Etiketi‘ne kendinizin tanıyacağı bir ad yazın, ör. “Halkbank”.
4. Yukarıdaki tablodaki dört bilgiyi ilgili alanlara girin.
5. İlk kurulumda Test Modu açık kalsın (“Bu hesap sağlayıcının test (sandbox) ortamını kullansın”). Test bilgileriyle çalışırken bu kutu işaretli olmalı.
6. Bayraklar bölümünde “Etkin — ödeme sayfasında sunulsun”u açın. Halkbank tek POS’unuzsa “Varsayılan hesap”ı da işaretleyin.
7. Taksit verecekseniz Taksit Oranları tablosunu doldurun (aşağıda anlatılıyor) ve POS Hesabını Kaydet‘e basın.
8. Hesap listesinde Bağlantıyı test et ile bilgilerin banka tarafından kabul edildiğini kontrol edin. Bu test ödeme çekmez, yalnız kimlik bilgilerini sınar.

Test ortamı ve canlıya geçiş

Test modunda Halkbank hesabı, NestPay’in ortak test sunucusuna bağlanır. Test mağaza bilgilerini ve test kartlarını Halkbank verir; eklentinin Test Kartları ekranında NestPay test ortamı için örnek kartlar da listelenir. Test siparişinde 3D Secure ekranının açıldığını, dönüşte siparişin ödendi olarak işaretlendiğini (“İşleniyor” ya da “Tamamlandı”) ve işlem kaydının oluştuğunu görün.

Canlıya geçerken test bilgilerini Halkbank’ın verdiği canlı bilgilerle değiştirin ve Test Modu‘nu kapatın. Test bilgisi canlı modda ya da canlı bilgi test modunda kullanılırsa banka kimliği tanımaz. İlk canlı ödemeyi küçük bir tutarla yapıp sanal POS panelinizden iptal etmek iyi bir son kontroldür.

Taksit ve BDDK sınırları

Halkbank’ın kendi kart programı Paraf’tır. Invum POS’un oran tablosunda “Genel (tüm kartlar)” oranlarının yanında Paraf gibi kart aileleri için ayrı oran girebilirsiniz. Her taksit için müşteriye yansıyacak vade farkını yazarsınız; 0 yazarsanız fark sizde kalır. Banka NestPay’de taksit oranlarını API’yle paylaşmadığı için değerleri Halkbank sözleşmenizdeki komisyon tablosundan alın. Farkın müşteriye etkisini komisyon hesaplama aracıyla önceden görebilirsiniz.

Banka kartı, ön ödemeli kart ve yurt dışı kartlarda taksit gösterilmez. Ürün grubuna göre azami taksit sayısı (ör. telefon, kuyum) eklentinin Taksit Uyumu ayarlarıyla otomatik sınırlanır; ayrıntılar BDDK taksit sınırları yazısında.

Sık karşılaşılan hatalar

• “Kimlik bulunamadı” ya da bağlantı testi başarısız: çoğu zaman test/canlı modu ile bilgiler uyuşmuyordur ya da API kullanıcısı yerine panel kullanıcısı girilmiştir.
• 3D doğrulaması başarısız (mdStatus 1 dışında): müşteri SMS şifresini girmemiş, kart 3D Secure’a kayıtlı değil ya da banka doğrulamayı reddetmiş olabilir. Invum POS NestPay’de yalnız tam doğrulanmış (mdStatus=1) ödemeleri kabul eder. Kodların anlamları POS ve banka hata kodları yazısında.
• Dönüşte imza hatası: Store Key yanlış girilmiştir; panelden kontrol edip yeniden yazın (ERR_3DS_CALLBACK_INVALID).
• “Banka 3D ağ geçidine ulaşılamadı”: sunucunuzun dışarıya bağlantısı, SSL sertifikası ya da bankanın IP kısıtı. Hosting firmanızla birlikte bakın.
• Red kodları (05, 51, 57…): kartı veren bankanın kararıdır; müşteriye başka kart denemesini önerin.

İade ve iptal

Eklentinin güncel sürümünde sipariş ekranındaki İade düğmesi iadeyi doğrudan Halkbank’a gönderir; parayı çeken POS hesabını ve işlemi eklenti kendisi bulur. Ödemeyle aynı gün tutarın tamamını iade ederseniz işlem iptal (void) olarak gider; banka gün sonunu kapatmışsa eklenti otomatik olarak normal iadeye geçer. Kısmi iade her zaman iade olarak gönderilir, böylece iptal yanlışlıkla tüm tutarı geri vermez. Bu akış NestPay test ortamında gerçek test işlemleriyle denendi. Banka bir iadeyi reddederse nedeni sipariş notuna yazılır; o durumda iadeyi Halkbank sanal POS panelinden yapıp WooCommerce siparişine kaydedebilirsiniz.