Bir e-pin veya dijital ürün sitesinde en kritik saniyeler ödeme anıdır: müşteri kart bilgisini girer, 3D Secure ekranı açılır, ardından ya ürün anında teslim olur ya da "işlem başarısız" yazısıyla karşılaşır ve bir daha geri gelmez. Sanal pos entegrasyonu, kağıt üzerinde birkaç API isteğinden ibaret görünse de gerçekte onlarca kenar durumun (edge case) yönetildiği bir sistemdir. Bu yazıda, e-pin ve dijital ürün satan sitelerin sanal pos tarafında en sık yaşadığı altı problemi ve bunların pratikte nasıl çözüldüğünü ele alıyoruz.
Sanal Pos Entegrasyonu Neden Bu Kadar Karmaşık Hissettiriyor?
Bir bankanın veya ödeme kuruluşunun (PayTR, Shopier, iyzico, param, sanal pos sağlayan bankalar) API dokümantasyonunu ilk açtığınızda genelde işlem basit görünür: istek at, yanıt al, ürünü teslim et. Ancak gerçek dünyada süreç şu adımlardan oluşur:
- Sipariş oluşturma ve hash/imza üretimi (her sağlayıcının kendi imzalama yöntemi vardır)
- Kullanıcıyı 3D Secure sayfasına yönlendirme
- Bankadan dönen POST/GET yanıtını doğrulama
- Sunucudan sunucuya gelen callback (bildirim) isteğini ayrıca doğrulama
- İki farklı doğrulamanın (kullanıcı dönüşü + sunucu bildirimi) çelişmesi durumunda hangisine güvenileceğine karar verme
- Başarısız, iptal, iade ve kısmi iade senaryolarını ayrı ayrı kodlama
E-pin sektöründe bu karmaşıklık daha da can yakıcı hale gelir, çünkü ürün genelde saniyeler içinde otomatik teslim edilir. Klasik bir e-ticaret sitesinde ödeme onaylanmadan kargo çıkmaz; ama bir e-pin sitesinde kod, ödeme "başarılı" göründüğü an ekrana basılabilir. Bu yüzden doğrulama zincirinde tek bir zayıf halka, hem gelir kaybına hem de kod hırsızlığına (chargeback + ürünü kaybetme) kapı aralar.
3D Secure Doğrulamasında Müşteriler Neden Yarı Yolda Kayboluyor?
Sanal pos entegrasyonlarında en yüksek terk oranı 3D Secure adımında yaşanır. Bunun birkaç teknik nedeni vardır:
- Mobil uyumsuz doğrulama sayfaları: Bankanın 3D ekranı responsive değilse, telefonda SMS kodu girme alanı ekran dışına taşabilir.
- Zaman aşımı: SMS gecikirse (özellikle yoğun saatlerde operatör tarafında), kullanıcı işlem tamamlanmadan sayfayı kapatır ve sipariş "yarım" durumda asılı kalır.
- Yönlendirme (redirect) zincirinin kopması: 3D sayfasından siteye dönüş URL'i yanlış yapılandırıldığında kullanıcı bankanın sayfasında takılı kalır, siparişin akıbeti belirsizleşir.
- Tarayıcı geri tuşu: Kullanıcı ödeme sırasında geri tuşuna basarsa, çift işlem denemesi veya çakışan sipariş kaydı oluşabilir.
Bu noktada asıl mesele "hatayı önlemek" değil, "yarım kalan işlemi doğru şekilde sonlandırabilmek"tir. Sistemin, kullanıcı 3D ekranından hiç dönmese bile bankadan gelecek asenkron bildirimle siparişi düzeltebilmesi gerekir. Aksi halde ya para tahsil edilir ama ürün teslim edilmez (müşteri kaybı ve destek yükü), ya da ürün teslim edilir ama para hiç geçmemiştir (doğrudan zarar).
Ödeme Bildirimi (Callback) Gelmezse Siparişe Ne Olur?
Sanal pos sağlayıcılarının çoğu, ödeme sonucunu iki kanaldan bildirir: kullanıcının tarayıcısı üzerinden dönüş (return URL) ve sunucudan sunucuya gönderilen bildirim (callback/webhook/bildirim URL). Sağlıklı bir entegrasyonda asıl güvenilecek kaynak ikincisidir, çünkü kullanıcı tarayıcısını kapatabilir ama banka sunucusu bildirimi mutlaka gönderir. Sorun şu ki, bu bildirim de her zaman sorunsuz ulaşmaz:
- Sunucu bakımda olabilir ve bildirim isteği 5xx hatası alıp geri dönmeyebilir
- Firewall veya güvenlik eklentisi, bankanın IP'sinden gelen isteği spam sanıp engelleyebilir
- Bildirim iki kez gönderilebilir (bankalar genelde tekrar dener) ve sistem aynı siparişi iki kez işleyip stoktan iki kod düşürebilir
- Bildirimdeki tutar veya sipariş numarası, sistemdeki kayıtla hash doğrulaması yapılmadan doğrudan güvenilirse, sahte bildirim gönderimiyle ürün çalınabilir
Doğru mimari; her bildirimi imza/hash ile doğrulayan, aynı sipariş için ikinci kez gelen bildirimi "zaten işlendi" diyerek sessizce reddeden, callback hiç gelmezse belirli aralıklarla bankaya durum sorgusu (status check) atan bir yapı kurmaktır. Bu, tek başına yazılması saatler süren ama gözden kaçırıldığında haftalar süren müşteri şikayetine dönüşen bir detaydır.
Callback URL'inizi sadece bankanın IP aralığından gelen isteklere açık tutmayın; ayrıca gelen her bildirimi kendi veritabanınızdaki sipariş kaydıyla tutar, para birimi ve sipariş numarası bazında karşılaştırın. Uyuşmayan tek bir alan bile varsa teslimatı durdurup manuel inceleme kuyruğuna alın.
Test Ortamından Canlıya Geçişte Sizi Hangi Sürprizler Bekliyor?
Sanal pos entegrasyonlarının çoğu, test (sandbox) ortamında sorunsuz çalışır ve geliştirici "bitti" der. Ancak canlıya geçişte karşılaşılan sorunlar genelde farklıdır:
- Test ortamındaki API anahtarları ile canlı anahtarların formatı/uzunluğu farklı olabilir ve kod bunu varsaymış olabilir
- Komisyon oranları ve taksit seçenekleri canlıda farklı hesaplanır, ürün fiyatına yansıtılmazsa mağaza zarar eder
- Gerçek bankalar arasında (özellikle farklı kartlı bankalar) 3D Secure davranışı ince farklılıklar gösterir; test ortamında tek bir sahte kartla denenen senaryo tüm bankaları temsil etmez
- SSL sertifikası, sunucu saat senkronizasyonu (NTP) veya IP kısıtlaması gibi altyapısal detaylar sandboxta zorunlu değilken canlıda reddedilme sebebi olabilir
Bu yüzden canlıya geçmeden önce gerçek ama düşük tutarlı bir işlemle (örneğin 1-5 TL) uçtan uca test yapmak, sadece "ödeme alındı mı" değil "callback geldi mi, ürün doğru teslim oldu mu, fatura/cari kayıt doğru mu" sorularının hepsini kontrol etmek gerekir.
Banka API'leri Neden Sürekli Değişiyor ve Entegrasyonu Bozuyor?
Bir sanal pos entegrasyonunu bir kez yazıp sonsuza kadar dokunmamak mümkün değildir. Bankalar ve ödeme kuruluşları düzenli olarak:
- 3D Secure protokol sürümünü günceller (örneğin eski 3DS1'den 3DS2'ye geçiş gibi)
- API endpoint'lerini veya parametre isimlerini değiştirir
- Güvenlik gerekçesiyle imzalama algoritmasını (hash yöntemini) günceller
- Belirli kart tiplerinde ek doğrulama adımları zorunlu kılar
Tek bir mağaza sahibi için bu değişiklikleri her bankada takip etmek pratik değildir; çünkü genelde duyuru e-postaları teknik ekibe değil, ticari temsilciye gider ve haber geç ulaşır. Sonuç, bir sabah aniden yükselen "ödeme alınamıyor" şikayetleridir. Bu riski azaltmanın yollarından biri, birden fazla mağazada aynı anda kullanılan ve bu yüzden değişiklikler fark edildiğinde merkezi olarak güncellenen bir ödeme altyapısı kullanmaktır — Pinova'nın PayTR, Shopier ve havale/EFT entegrasyonlarını hazır modül olarak sunmasının pratik nedeni de budur; banka tarafındaki değişiklik tek bir yerde düzeltilir, tüm kurulumlar bundan faydalanır.
Birden Fazla Sanal Pos'u Aynı Anda Yönetmek Gerçekten Mümkün mü?
Büyüyen e-pin ve dijital ürün siteleri genelde tek bir ödeme sağlayıcıya bağlı kalmak istemez: biri komisyon avantajı sağlar, diğeri belirli banka kartlarında daha az ret alır, üçüncüsü yedek olarak tutulur. Ancak birden fazla sanal pos'u aynı sistemde çalıştırmak yeni sorunlar doğurur:
- Her sağlayıcının callback formatı, hata kodları ve durum isimleri farklıdır; ortak bir "sipariş durumu" mantığına çevirmek gerekir
- Müşteriye hangi yöntemin gösterileceği (öncelik sırası, bakiyeye göre otomatik geçiş) manuel yönetilirse zamanla karmaşıklaşır
- Muhasebe tarafında farklı sağlayıcılardan gelen komisyon kesintilerini ayrı ayrı takip etmek gerekir
- Bir sağlayıcı geçici olarak arıza yaşadığında diğerine otomatik yönlendirme yapılmazsa satış tamamen durur
Bu ihtiyaç, özellikle sitesini büyüten e-pin işletmelerinin "artık her ödeme entegrasyonunu ayrı ayrı yazmak istemiyoruz" dediği noktadır. Aşağıdaki tablo, bu süreci elle (özel yazılımla sıfırdan) yürütmekle hazır bir altyapı kullanmak arasındaki pratik farkı özetliyor:
| Konu | Manuel / Elle | Pinova ile |
|---|---|---|
| Yeni ödeme yöntemi ekleme | Sıfırdan API entegrasyonu, günler süren geliştirme | Panelden aktif/pasif, hazır modül |
| Callback doğrulama ve çakışma yönetimi | Geliştiriciye bağlı, hataya açık | Merkezi, test edilmiş doğrulama katmanı |
| Yarım kalan / şüpheli işlemler | Manuel log inceleme | Otomatik durum sorgusu + admin uyarısı |
| Banka API değişiklikleri | Her mağaza kendi başına takip eder | Merkezi güncelleme, tüm kurulumlara yansır |
| Çoklu sağlayıcı arasında öncelik/yedekleme | Özel kod yazımı gerekir | Ayarlardan yönetilen sıralama |
Bu Sorunları Sıfırdan mı Çözeceksiniz, Yoksa Hazır Altyapı mı Kullanacaksınız?
Pinova, PayTR, Shopier ve havale/EFT ödeme yöntemlerini, callback doğrulama ve otomatik teslimat mantığıyla birlikte hazır sunar; e-pin sitenizde ödeme tarafını sıfırdan kodlamak yerine test edilmiş bir altyapı üzerine kurabilirsiniz.
Sanal pos entegrasyonunda en sık hangi hata alınır?
En sık karşılaşılan hata, 3D Secure sonrası kullanıcının siteye dönüşü ile bankadan gelen sunucu bildiriminin (callback) çakışması veya callback'in hiç ulaşmamasıdır. Bu durumda sipariş "beklemede" kalır ve manuel müdahale gerekir.
E-pin sitelerinde ödeme onayı gelmeden ürün teslim edilirse ne olur?
Ödeme henüz kesin onaylanmadan kod teslim edilirse, işlem daha sonra iptal/red olduğunda kod zaten kullanıcıya gitmiş olur ve geri alınamaz; bu doğrudan finansal kayıptır. Bu yüzden teslimat, yalnızca doğrulanmış callback sonrası tetiklenmelidir.
Birden fazla sanal pos kullanmak satışları artırır mı?
Genellikle evet; farklı bankalarda ret oranları farklılaştığı için ikinci bir sağlayıcı, birinde reddedilen işlemleri kurtarabilir. Ancak bunun faydalı olması için sağlayıcılar arası otomatik yönlendirme ve ortak durum takibi gerekir, aksi halde yönetim yükü artar.
Pinova hangi ödeme yöntemlerini destekliyor?
Pinova; PayTR, Shopier ve havale/EFT dahil olmak üzere birden fazla ödeme yöntemini hazır modül olarak sunar, ayrıca site içi cüzdan/bakiye sistemiyle müşterilerin önceden yükledikleri bakiyeden anında alışveriş yapmasına imkan tanır.