Sanal POS Entegrasyonu Nasıl Yapılır? API, 3D ve Test

Sanal POS başvurunuz onaylandığında elinize bir mağaza numarası ve birkaç gizli anahtar geçer. Sanal POS entegrasyonu, bu bilgilerle sitenizin ödeme adımını sağlayıcıya bağlama işidir: kart bilgisinin nerede alınacağı, 3D Secure yönlendirmesi, ödeme sonucunun siparişe nasıl işleneceği ve iadenin nasıl yapılacağı.

Yazı platformdan bağımsızdır, kod içermez; amaç kurulumu yapan ekiple aynı dili konuşmanız. Kavramın kendisi için sanal POS nedir yazısına, ödemenin genel akışı için kartlı ödemenin 6 adımı bölümüne bakabilirsiniz.

Üç entegrasyon yolu: ortak ödeme sayfası, iframe ve doğrudan API

Sağlayıcıların çoğu birden fazla yol sunar; fark, müşterinin kart bilgisini nerede girdiğidir.

• Ortak ödeme sayfası: Müşteri sağlayıcının ya da bankanın sayfasında öder, sonra sitenize döner. DenizBank bu sayfayı, sitenizde ayrıca ödeme sayfası düzenlemeniz gerekmeyen, bakımı ve güvenliği bankada olan bir hizmet olarak tanımlar.
• Gömülü form (iframe): Ödeme formu sitenizin içinde açılır ama kart alanları sağlayıcıdan gelir. PayTR'ın iFrame API'si bu türdendir.
• Doğrudan API: Kart formunu siz tasarlarsınız; kart bilgisi sunucunuzdan sağlayıcıya iletilir. PayTR bu yola Direkt API, iyzico 3DS ve Non-3DS API der.

Kart verisinin kimde kaldığı güvenlik yükünüzü belirler; ayrıntısı 3D Secure ve PCI DSS yazısında.

Hazır platformlarda bu yollardan biri bir eklentiyle paketlenir; aşağıdaki bildirim ve test adımları yine geçerlidir. Platforma özel ayrıntılar için WordPress ve WooCommerce sanal POS entegrasyonu ile Shopify'da sanal POS sayfalarımıza bakın.

3D Secure akışı ve dönüş (callback) adresi

3D Secure'de müşteri, kartını veren bankanın ekranında ödemeyi SMS şifresi ya da uygulama onayıyla onaylar. Doğrulamayı banka yapar; akışı başlatan ve sonucu karşılayan sizin entegrasyonunuzdur. Bu akışta iki ayrı adres tanımlanır ve en sık hata ikisini karıştırmaktır:

• Tarayıcı dönüş adresi: Müşterinin ödeme bitince gördüğü "başarılı" ya da "başarısız" sayfası.
• Sunucu bildirim adresi: Sağlayıcının, müşteriden bağımsız olarak ödeme sonucunu arka planda sunucunuza gönderdiği adres. PayTR buna Bildirim URL, iyzico webhook der.

PayTR'ın belgesi farkı açıkça yazar: altyapı asenkron çalışır; müşteri başarılı sayfasına yönlenirken kesin sonuç Bildirim URL'ye gönderilir. Bu yüzden başarılı sayfasında sipariş onayı ya da iptali yapılmamalıdır (PayTR iFrame API 1. adım). Bildirim adresine üye girişi gibi bir kısıt konmaz; sipariş, oturumla değil sipariş numarasıyla bulunur (PayTR iFrame API 2. adım).

iyzico'nun 3DS akışı başlatma, doğrulama sayfasına yönlendirme, dönüş adresine (callbackUrl) geri gelme ve 3DS tamamlama adımlarından oluşur; webhook bunlara ek bir bildirimdir (iyzico 3DS entegrasyonu). Bankanın kendi sanal POS'unda adımların adı değişir, mantık aynı kalır.

Sipariş ne zaman onaylanır? Hash, imza ve çift sipariş tuzağı

Entegrasyonun en önemli kuralı tek cümledir: sipariş yalnız sağlayıcının doğrulanmış bildirimiyle onaylanır. Tarayıcı dönüşü ödemenin kanıtı değildir.

"Doğrulanmış" iki şey demektir:

• İmza (hash) kontrolü: Sağlayıcı bildirimle birlikte gizli anahtarınızla üretilmiş bir imza gönderir; siz aynısını hesaplayıp karşılaştırırsınız. PayTR bu kontrol yapılmazsa maddi kayıp yaşanabileceğini yazar (PayTR bildirim belgesi). iyzico, yanıtlardaki imzanın gizli anahtarla HMAC SHA256 kullanılarak doğrulanmasını ister (iyzico imza doğrulama).
• İçerik kontrolü: Bildirimdeki sipariş numarası sizde var mı, tutar beklediğinizle uyuşuyor mu? PayTR'a göre müşteri vade farklı taksit seçtiğinde tahsil edilen toplam, gönderdiğiniz sipariş tutarından yüksek olabilir. Karşılaştırmayı bunu bilerek kurun.

Çift sipariş tuzağı bildirimin birden fazla gelmesinden doğar. PayTR, ağ sorunları ya da sitenizdeki anlık yoğunluk yüzünden aynı ödeme için birden fazla bildirim gelebileceğini, yalnız ilkinin dikkate alınması gerektiğini yazar (kaynak). iyzico ise sunucunuz başarılı bir yanıt dönene kadar webhook'u aralıklarla yeniden gönderir (iyzico webhook). Önlemler:

• Her ödeme denemesine benzersiz bir sipariş numarası verin; PayTR bu numarayı zaten benzersiz ister.
• Bildirimi işlemeden önce siparişin durumuna bakın. Sipariş onaylanmışsa yalnız "alındı" yanıtı verin; stok düşmeyi ve kargo kaydını tekrarlamayın.
• Sağlayıcının beklediği yanıtı tam biçimiyle dönün. PayTR yalnız "OK" metni bekler; alamazsa işlem panelde "Devam Ediyor" görünür.
• Bildirim hiç gelmediyse tahmin yürütmeyin; sonucu sağlayıcının durum sorgu servisiyle sorgulayın.

Test ortamı ve test kartları: canlıya geçmeden ne denenir?

Her sağlayıcı gerçek para çekmeden deneme imkânı verir; yöntem farklıdır:

• PayTR: iFrame API'de test kart bilgileri ödeme sayfasında hazır gelir; Direkt API için ayrı bir test kartları sayfası var. Testten sonra panelden canlı moda geçiş talebi gönderilir, PayTR test işlemlerini kontrol edip mağazayı canlıya alır (PayTR entegrasyon süreci).
• iyzico: Ayrı bir sandbox hesabı ve canlıdan tamamen farklı API anahtarları kullanılır (iyzico live ve sandbox). Sandbox'ta gerçek kartla işlem desteklenmez. iyzico, başarılı ödeme veren kartların yanında yetersiz bakiye, çalıntı kart ya da 3DS başlatılamadı gibi hataları üreten test kartları da yayımlar.
• Bankalar: Test bilgileri ve dokümanlar genellikle başvuru onayından sonra paylaşılır; DenizBank örneğin uygun yöntemi teknik ekibinin belirleyip örnek kod ve prosedürleri paylaştığını yazar.

Test kartı numaralarını her zaman belgenin güncel halinden alın. Asıl önemli olan neyi denediğinizdir:

• Başarılı tek çekim ve taksitli ödeme.
• Reddedilen kart: müşteri anlaşılır bir hata ve tekrar deneme yolu görüyor mu?
• 3D ekranında vazgeçme ya da sayfayı kapatma: sipariş "ödendi"ye geçmemeli, stok düşmemeli.
• Aynı bildirimin iki kez gelmesi: ikinci sipariş açılmamalı.
• Tam ve kısmi iade: tutar sağlayıcı panelinde ve mağaza siparişinde aynı görünmeli.

İade ve iptalin entegrasyondaki yeri

Parayı geri vermek de aynı bağlantıdan geçer ve iki ayrı işlemdir:

• İptal: Ödemenin alındığı gün, banka kendi mutabakatını yapmadan önce yapılır. iyzico'ya göre iptal kart ekstresinde kayıt oluşturmaz ve kısmi tutarı desteklemez.
• İade: Sonraki günlerde yapılır; tutarın tamamı ya da bir kısmı için olabilir. iyzico'da bir ödeme 365 gün içinde iade edilebilir; kalan tutarı aşmamak koşuluyla art arda kısmi iade yapılabilir (iyzico iptal ve iade). PayTR'ın iade servisi de siparişin tamamı ya da bir kısmı için çalışır.

PayTR, yanlış kurulmuş bir iade entegrasyonunun hatalı iadelere ve maddi kayba yol açabileceği uyarısını yapar. İki kural öne çıkar: iade tutarı kalan iade edilebilir tutarı aşmamalı, sipariş de sağlayıcının yanıtı doğrulanmadan "iade edildi" diye işaretlenmemeli. İadeyi sağlayıcı panelinden yaparsanız mağazadaki siparişi de eşitleyin; iadeleri siparişle birlikte izlemek için sipariş yönetimi sayfamıza bakabilirsiniz.

Bankaya doğrudan bağlanmak: EST v3, Payflex, Posnet ve Interpos

Bankanın kendi sanal POS'unda her banka ayrı başvuru, ayrı anahtar ve ayrı test demektir. Bankalar bu bağlantıyı birkaç altyapı ailesi üzerinden sunar. Aynı aileyi kullanan bankalar tek bir bağlantı koduyla, banka başına farklı adres ve kimlik bilgileriyle bağlanabilir.

Bankalar da birden çok yöntem sunar: VakıfBank'ın sanal POS kılavuzları sayfasında entegrasyon dokümanlarının yanında ayrı bir Güvenli Ortak Ödeme dokümanı var. İki modelin bakım yükünü banka sanal POS'u mu, ödeme kuruluşu mu yazısında karşılaştırdık.

Canlıya geçmeden 10 maddelik kontrol listesi

1. Canlı ve test anahtarları ayrı; gizli anahtar yalnız sunucuda.
2. Ödeme yolu (ortak sayfa, iframe, API) seçildi ve PCI DSS yükünün kimde olduğu netleşti.
3. 3D Secure açık; 3D'siz işleme izin varsa koşulu sözleşmede yazılı.
4. Sunucu bildirim adresi HTTPS, erişim kısıtı yok ve sağlayıcı panelinde doğru tanımlı.
5. Her bildirimde imza doğrulanıyor; imzası tutmayan bildirim reddediliyor.
6. Sipariş numarası benzersiz; tekrarlayan bildirim ikinci sipariş açmıyor.
7. Tarayıcı dönüş sayfası siparişi onaylamıyor, yalnız durumu gösteriyor.
8. Başarılı, reddedilen, vazgeçilen ve taksitli ödeme test ortamında denendi.
9. Tam ve kısmi iade denendi; tutar sağlayıcı panelinde ve siparişte aynı.
10. Canlıda küçük tutarlı gerçek bir ödeme alınıp iade edildi, rapor siparişlerle karşılaştırıldı.

Mubido'da sanal POS entegrasyonu

Mubido'da 13 ödeme bağlantısı kodda yazılı. PayTR, iyzico, Sipay, Garanti BBVA ve Kuveyt Türk bağlantıları canlı mağazalarda tahsilat yaptı. EST v3 (İş Bankası, Akbank, Halkbank, Ziraat Bankası), Payflex (VakıfBank, Ziraat Bankası, İş Bankası), Posnet (Yapı Kredi), Interpos (DenizBank), Vakıf Katılım ve N Kolay bağlantıları ilk kurulumda sizin hesabınızla test edilir.

Kurulumda sağlayıcınızın verdiği bilgileri biz tanımlar, 3D Secure ve iade akışını test edip mağazayı satışa açarız. Kart verisi Mubido'da tutulmaz; sağlayıcının sayfasında ve altyapısında işlenir. Mubido bir ödeme kuruluşu değildir, para tutmaz: sözleşmeniz ve oranınız seçtiğiniz banka ya da ödeme kuruluşuyla aranızdadır.

Hazır bağlantıları sanal POS firmaları karşılaştırmasında listeledik. Ayrıntılar için PayTR sanal POS ve iyzico sanal POS yazılarına, mağaza tarafı için online mağaza sayfamıza bakın.