Sanal POS Entegrasyonu: API, iFrame, Hazır Ödeme Sayfası ve Eklenti Seçenekleri

Sanal POS entegrasyonu, bir e-ticaret sitesinin veya mobil uygulamanın ödeme geçidine teknik olarak bağlanmasını sağlar. Doğru kurulan bir entegrasyonla işletme, her banka için ayrı anlaşma yapmadan farklı bankaların kartlarıyla tek bir sanal POS üzerinden tahsilat alabilir. Bu bağlantı üç ana model üzerinden kurulur: API tabanlı entegrasyon, iFrame tabanlı entegrasyon ve hazır ödeme sayfasına yönlendirme. Kod yazmak istemeyen işletmeler için bu modellerin üzerine kurulmuş açık kaynak eklentiler ve hazır e-ticaret altyapısı entegrasyonları da bulunur.

Modeller arasındaki fark yalnızca görünümden ibaret değildir. Kart bilgisinin nerede işlendiği, ödeme formunun kim tarafından barındırıldığı ve güvenlik sorumluluğunun hangi tarafta kaldığı modelden modele değişir. Doğru seçim; teknik ekibin yeterliliğine, ödeme adımında kullanıcı deneyimi kontrolünün ne kadar önemli olduğuna ve PCI-DSS sorumluluğunun işletmede mi yoksa ödeme kuruluşunda mı kalacağına bağlıdır.

Sanal POS Entegrasyonunda Hangi Modeller Kullanılır?

Üç model de kart bilgisini toplayıp ödeme kuruluşuna iletme işini yapar; farklılaşan nokta işlem akışının nerede yürütüldüğü ve teknik sorumluluğun kimde kaldığıdır. 3D Secure doğrulaması ise her üç modelde de devreye girer; bu nedenle modeller arasındaki fark güvenlik seviyesi değil, teknik sorumluluk dağılımıdır.

API Tabanlı Entegrasyon

API entegrasyonunda ödeme formu işletmenin kendi sitesinde tasarlanır ve kart verisi işletmenin sunucusu üzerinden ödeme kuruluşunun API’sine iletilir. İstek-yanıt döngüsü tamamen sunucu tarafında yürür. Bu akış ödeme formunun tasarımı üzerinde tam kontrol sağlar; kullanıcı ödeme sırasında sayfadan ayrılmaz ve sitenin görsel bütünlüğü korunur.

Kart verisinin işletme sunucusundan geçmesi, teknik ve güvenlik yükünün büyük bölümünü işletmeye taşır. Token oluşturma, imza doğrulama ve hata yönetimi backend tarafında yazılmalı, sunucu geçerli bir SSL sertifikasıyla korunmalıdır. Bu nedenle model, yazılım kaynağı güçlü işletmeler için daha uygundur. PayTR’de bu model Direkt API adıyla sunulur.

iFrame Tabanlı Entegrasyon

iFrame entegrasyonunda ödeme kuruluşunun sunucusunda barındırılan ödeme formu, işletmenin sayfasına gömülü bir çerçeve olarak yerleştirilir. Kullanıcı siteden ayrılmadan işlemini tamamlar, ancak kart verisi doğrudan ödeme kuruluşunun altyapısına gider ve işletmenin sunucusuna uğramaz. PayTR’de bu model iFrame API olarak sunulur.

Modelin sorunsuz çalışması X-Frame-Options ve SameSite çerez ayarlarının doğru yapılandırılmasına bağlıdır; yanlış bir başlık ayarı çerçevenin hiç açılmamasına ya da 3D Secure yönlendirmesinin kesilmesine yol açabilir. iFrame, API’ye göre daha az geliştirme yükü taşırken kullanıcıyı sitede tutma avantajını korur ve PCI-DSS kapsamının büyük kısmını ödeme kuruluşuna bırakır.

Hazır Ödeme Sayfası Yönlendirmesi

Bu modelde kullanıcı, ödeme adımında ödeme kuruluşunun kendi alan adındaki sayfaya yönlendirilir. Kart bilgisi işletmenin sunucusuna hiçbir aşamada temas etmez. İşlem sonucu callback URL üzerinden işletmenin sistemine bildirilir; sipariş durumu ve stok düşümü bu bildirime göre güncellenir.

İşletme tarafında yalnızca yönlendirmeyi başlatacak ve callback URL’yi karşılayacak basit bir uç nokta yazmak yeterli olduğu için üç model içinde en az teknik yük gerektiren seçenektir. Karşılığında ödeme sayfasının görünümü üzerindeki kontrol sınırlıdır ve kullanıcı işlem süresince sitenin dışına çıkar.

Hazır Altyapılarla Sanal POS Entegrasyonu Nasıl Yapılır?

Kendi kodunu yazmak istemeyen işletmeler, kullandıkları e-ticaret yazılımı için geliştirilmiş hazır eklentiler üzerinden entegrasyon yapabilir. Bu eklentiler arka planda yukarıdaki modellerden birini kullanır; işletme yalnızca mağaza bilgilerini ve API anahtarlarını panele girerek kurulumu tamamlar.

Açık Kaynak Sanal POS Entegrasyonları

Açık kaynak yazılımlarda entegrasyon, ödeme kuruluşunun sunduğu eklenti veya modülün kurulmasıyla yapılır. Sanal POS eklentisi bulunan başlıca açık kaynak altyapılar şunlardır:

1. WooCommerce (WordPress)
2. PrestaShop
3. OpenCart
4. Magento
5. nopCommerce
6. VirtueMart
7. Drupal
8. WHMCS
9. Perfex
10. XenForo

Güncel liste ve eklenti dosyaları açık kaynaklı altyapılar sayfasında yer alır.

Hazır E-Ticaret Altyapıları Sanal POS Entegrasyonları

Hazır e-ticaret altyapılarında entegrasyon genellikle yönetim panelindeki ödeme ayarlarından ödeme kuruluşunun seçilmesi ve mağaza bilgilerinin girilmesiyle tamamlanır. Sanal POS entegrasyonu sunan başlıca altyapılar şunlardır:

11. Shopify
12. Wix
13. Ticimax
14. T-Soft
15. IdeaSoft
16. PlatinMarket
17. İmağaza
18. KMK
19. DemirExport
20. BilgiKurumsal
21. ShopPHP
22. SoftArt
23. Projesoft
24. Fabrika
25. Akınsoft

Güncel liste hazır altyapılar sayfasında yer alır. Kullanılan yazılım listede yoksa entegrasyon API veya iFrame ile doğrudan yapılabilir.

API, iFrame ve Hazır Ödeme Sayfası Nasıl Karşılaştırılır?

Hiçbir model tüm ölçütlerde diğerlerinden üstün değildir; seçim, işletmenin teknik kapasitesine ve önceliklerine göre değişir.

Ölçüt	API	iFrame	Hazır Ödeme Sayfası
Geliştirme süresi	Uzun	Orta	Kısa
Kullanıcı deneyimi	Kesintisiz	Kesintisiz	Yönlendirmeli
Güvenlik sorumluluğu	Geniş kapsam	Orta kapsam	Dar kapsam
Sürdürülebilirlik	Esnek, yüklü bakım	Dengeli	Düşük bakım, sınırlı esneklik

Teknik Ekip ve Geliştirme Süresi

API entegrasyonu, ödeme formundan hata yönetimine kadar her adımın işletme tarafından kodlanmasını gerektirdiği için en uzun geliştirme süresine ve deneyimli bir yazılım ekibine ihtiyaç duyar. iFrame orta düzeyde teknik bilgi ister; form ödeme kuruluşunda barındırıldığı için ayrıca kodlanmaz, ancak güvenlik başlıkları ve çerez ayarları ek test süresi gerektirir. Hazır ödeme sayfası ve hazır altyapı eklentileri ise neredeyse hiç geliştirme gerektirmez.

Kullanıcı Deneyimi

API ve iFrame kesintisiz bir akış sunar; müşteri ödeme sırasında siteden ayrılmaz ve marka bütünlüğü korunur. Hazır ödeme sayfasında kullanıcı ödeme kuruluşunun sayfasına yönlendirilip işlem sonunda siteye döner. Bu adım bazı kullanıcılarda güven tereddüdü yaratabilir, ancak kurulumun basitliği bu dezavantajı dengeler.

Güvenlik ve PCI-DSS Sorumluluğu

Sorumluluk, kart verisiyle temas derecesine göre değişir. API modelinde kart bilgisi işletmenin sunucusundan geçtiği için PCI-DSS kapsamı en geniştir ve kart verisinin işlendiği her nokta denetime girer. Hazır ödeme sayfasında kart verisi işletmeye hiç ulaşmadığından kapsam en dardır. iFrame bu iki uç arasında yer alır; form ödeme kuruluşunda barındırılsa da entegrasyonun genel güvenlik ayarları işletme tarafından takip edilmelidir.

Bakım ve Sürdürülebilirlik

API, sağlayıcı değişikliklerine ve yeni özelliklere en hızlı uyum sağlayan modeldir ama dokümantasyondaki her değişikliğin takip edilmesini gerektirir. Hazır ödeme sayfası düşük bakım maliyeti sunar, buna karşılık tasarım ve akış üzerinde söz hakkı sınırlıdır. iFrame, tarayıcı politikaları değiştiğinde ara sıra güncelleme gerektirir; hazır altyapı eklentilerinde ise eklentinin güncel tutulması yeterlidir.

Sanal POS Entegrasyonu Hangi Adımlarla Kurulur?

Seçilen model ne olursa olsun kurulum aynı sırayı izler: test ortamı kurulur, güvenlik ayarları yapılır, bildirim akışı tanımlanır ve sistem canlıya alınır.

Sandbox Test Ortamının Kurulması

Sandbox, gerçek para hareketi olmadan ödeme akışının test edildiği ortamdır; ödeme kuruluşları bu ortam için test kartı numaraları ve test API anahtarları sunar. Başarılı ödeme, başarısız ödeme, 3D Secure onayı ve iptal senaryoları ayrı ayrı denenir. Token doğrulamasında alan sırasının dokümantasyondan farklı olması gibi küçük yapılandırma hataları bu aşamada yakalanır.

SSL Sertifikası ve Güvenlik Başlıklarının Ayarlanması

SSL sertifikası her modelde zorunludur; site ile ödeme kuruluşu arasında iletilen verilerin okunmasını ve değiştirilmesini engeller ve sertifikasız bir sitede kart verisi iletimi kabul edilmez. Güçlü şifreleme ve PCI-DSS uyumluluğu ile birlikte doğru kurulan bir sanal POS, en az fiziki POS kadar güvenli bir tahsilat kanalıdır. iFrame entegrasyonunda ayrıca X-Frame-Options başlığı ve SameSite çerez ayarları gözden geçirilmelidir; yanlış yapılandırmada form hiç yüklenmeyebilir.

Callback URL ve Bildirim Akışının Tanımlanması

Callback URL, ödeme kuruluşunun işlem sonucunu işletmenin sunucusuna bildirdiği adrestir ve API ile hazır ödeme sayfası modellerinde zorunludur. Bildirim bir hash veya imza ile gelir; işletme bu imzayı doğrulayarak bildirimin gerçekten ödeme kuruluşundan geldiğinden emin olur. İmza doğrulaması atlanırsa sahte bildirimlerle sipariş durumunun yanlış güncellenmesi riski doğar.

Canlı Ortama Geçiş

Sandbox testleri tamamlandıktan sonra test API anahtarları canlı anahtarlarla değiştirilir. API entegrasyonunda ek kod incelemesi, iFrame’de header ve çerez ayarlarının yeniden kontrolü gerekebilir; hazır ödeme sayfasında geçiş genellikle panelden verilen bir onaya indirgenir. İlk saatlerde küçük hacimli gerçek işlemlerle akışın uçtan uca doğru çalıştığı teyit edilmelidir.

Entegrasyon Sonucu Ne Zaman ve Nasıl Görülür?

Sandbox onayının ardından canlıya geçiş genellikle birkaç iş günü içinde tamamlanır. Hazır ödeme sayfasında süreç daha hızlı ilerlerken, API entegrasyonlarında ek kod incelemesi nedeniyle onay biraz daha uzun sürebilir.

Canlıya geçişten sonra üç kontrol noktası takip edilmelidir: 3D Secure onayının doğru tamamlanması, callback bildiriminin işletme sistemine ulaşması ve tutarın ilgili hesaba doğru yansıması. Bunlardan biri eksik kalırsa görünürde başarılı bir ödeme bile muhasebe tarafında tutarsızlığa yol açabilir. Entegrasyon genellikle ilk birkaç gün içinde stabilize olur.

Uygulamada en sık gecikme sebebi dokümantasyondan küçük sapmalardır. Nitekim bir e-ticaret sitesi sahibinin PayTR iFrame entegrasyonu deneyiminde, hash hesaplamasındaki tek bir alan sırası farkı token doğrulamasını tamamen durdurmuş ve planlanan sürenin çok üzerinde zaman almıştır.

PayTR ile Sanal POS Entegrasyonu

PayTR’de kendi ödeme formunu tasarlamak isteyen işletmeler Direkt API’yi, formu sitesine gömmek isteyenler iFrame API’yi kullanabilir. Açık kaynak ve hazır e-ticaret altyapısı kullanan işletmeler ise hazır eklentilerle entegrasyonu kod yazmadan tamamlayabilir. Kredi kartı, banka kartı ve dijital cüzdan gibi ödeme yöntemleri tek entegrasyonla kabul edilir, ödeme raporları panelden takip edilir. Tüm seçenekler entegrasyonlar sayfasında yer alır; kurulum sürecinde geliştirici kılavuzları, canlı destek ve müşteri temsilcileri destek sağlar.

Sıkça Sorulan Sorular

API, iFrame ve hazır ödeme sayfası arasındaki temel fark nedir?

Temel fark, kart verisinin nerede işlendiğidir. API’de kart verisi işletmenin sunucusundan geçer, iFrame’de işletmenin sayfasına gömülü ancak ödeme kuruluşunda barındırılan bir formda işlenir, hazır ödeme sayfasında ise tamamen ödeme kuruluşunun sayfasında kalır.

PayTR ile sanal POS entegrasyonu nasıl yapılır?

Direkt API, iFrame API veya açık kaynak ve hazır e-ticaret altyapıları için sunulan eklentiler üzerinden yapılır. Entegrasyon kılavuzları adım adım yol gösterir; sorunlarda canlı destek ve müşteri temsilcileri destek sağlar.

PayTR’nin sanal POS entegrasyonu işletmelere hangi avantajları sağlar?

Banka kartı, kredi kartı ve dijital cüzdan gibi farklı ödeme yöntemlerini tek sistemde sunar. Ödeme raporlaması, veri gizliliği ve farklı akıllı cihazlarla uyum, işletmenin operasyonel yükünü azaltır ve alıcıya kolay bir ödeme deneyimi sağlar.

Sanal POS entegrasyonunda karşılaşılan teknik zorluklar nelerdir?

En sık karşılaşılan zorluklar; entegre edilecek yazılımdaki uyumsuzluklar, PCI-DSS uyum gereklilikleri ve hash ya da token doğrulamasındaki yapılandırma hatalarıdır. Bu sorunların büyük bölümü sandbox testleri, entegrasyon kılavuzları ve canlı destekle çözülebilir.