Sanal POS Entegrasyonu: iyzico, PayTR, Param Teknik Rehber

Sanal POS Entegrasyonu: iyzico, PayTR, Param Teknik Rehber

E-ticaret sitesi kurarken en çok ertelenen ama en kritik adımlardan biri sanal POS entegrasyonudur. Ürün kataloğu hazır, tasarım bitmiş, kargo entegrasyonu kurulmuş olabilir — ama ödeme alamayan bir site, site değil sadece bir kataloğdur. Türkiye'de sanal POS pazarının büyük kısmını iyzico, PayTR ve Param paylaşıyor; üçü de bankalarla anlaşmalı, 3D Secure destekli, API tabanlı ödeme altyapıları sunuyor. Ancak entegrasyon mimarileri, dokümantasyon kaliteleri ve teknik gereksinimleri birbirinden belirgin şekilde farklı.

Bu rehberde üç sağlayıcının teknik entegrasyon yöntemlerini, kod seviyesinde nasıl çalıştıklarını, güvenlik gereksinimlerini ve sunucu tarafında nelere dikkat etmeniz gerektiğini ele alıyoruz. Amaç pazarlama karşılaştırması değil, entegrasyonu yapacak geliştiricinin veya teknik kararı verecek e-ticaret sahibinin ihtiyaç duyacağı somut bilgi.

Sanal POS Nedir, E-Ticaret Sitesine Neden Gerekli?

Sanal POS, fiziksel bir POS cihazının internet üzerinden çalışan karşılığıdır. Müşteri kart bilgilerini girer, işlem bankanın veya ödeme kuruluşunun sunucularına iletilir, 3D Secure doğrulaması yapılır ve sonuç sitenize geri döner. Aradaki tüm bu trafiği yöneten katman ödeme kuruluşudur (payment service provider).

Türkiye'de iki yol var:

• Doğrudan banka sanal POS'u: Bankayla ayrı sözleşme, ayrı entegrasyon, genelde tek banka desteği.
• Ödeme kuruluşu üzerinden entegrasyon: iyzico, PayTR, Param gibi aracı kuruluşlar birden fazla bankanın POS'unu tek bir API arkasında birleştirir; tek entegrasyonla çoklu banka desteği, taksit seçenekleri ve ortak raporlama alırsınız.

Küçük ve orta ölçekli e-ticaret siteleri için ikinci yol neredeyse her zaman daha mantıklıdır: tek sözleşme, tek API, tek destek hattı. Platform seçimini henüz netleştirmediyseniz e-ticaret sitesi kurulumu ve teknik altyapı seçimi yazımızda sanal POS entegrasyonunun da bir parçası olduğu genel mimari kararları detaylı işledik.

Büyükweb notu: Sanal POS entegrasyonu "eklenti kur, API anahtarını yapıştır" kadar basit değil. Callback URL'lerinin doğru çalışması, sunucunun dış IP'lere giden isteklerde zaman aşımı yaşamaması ve SSL sertifikasının kesintisiz geçerli olması entegrasyonun başarısını doğrudan etkiliyor. Bu üçü de sunucu tarafı konfigürasyonla ilgili, kod kalitesiyle değil.

iyzico, PayTR ve Param Arasındaki Teknik Farklar

Üç sağlayıcı da benzer bir iş yapıyor ama entegrasyon deneyimi farklılaşıyor.

Özellik	iyzico	PayTR	Param
Entegrasyon yöntemi	REST API + Checkout Form	iFrame/API token tabanlı	SOAP/REST hibrit API
Resmi SDK	PHP, Node.js, Java, Python	PHP örnek kodlar	PHP, .NET örnekleri
3D Secure akışı	Zorunlu/opsiyonel seçilebilir	Zorunlu (iFrame içinde)	Zorunlu/opsiyonel
Taksit desteği	Var, API üzerinden sorgulanabilir	Var	Var
Test (sandbox) ortamı	Var	Var	Var
Webhook/callback yapısı	Callback URL + conversationId	Merchant OID + hash doğrulama	Callback URL + hash doğrulama

iyzico, en olgun ve en çok dilde SDK sunan sağlayıcı. Checkout Form entegrasyonu ile kart bilgileri hiç kendi sunucunuza dokunmadan doğrudan iyzico'nun barındırdığı forma gidiyor — bu, PCI DSS yükünüzü ciddi şekilde azaltıyor.

PayTR iFrame tabanlı çalışıyor; ödeme formu bir iframe içinde açılıyor ve kart verisi yine sizin sunucunuza dokunmuyor. Token oluşturma isteğini siz sunucu tarafında atıyorsunuz, formu ise PayTR barındırıyor.

Param, hem doğrudan API (kart bilgisi sizin sunucunuzdan geçiyor, dolayısıyla PCI DSS yükümlülüğünüz artıyor) hem de 3D Secure yönlendirmeli model sunuyor. Yeni başlayan projeler için 3D Secure yönlendirmeli model önerilir çünkü kart verisinin sunucunuzdan geçmemesi güvenlik açısından çok daha avantajlı.

Sanal POS Entegrasyon Yöntemleri: API, iFrame, Yönlendirme

Entegrasyon mimarisini seçerken üç temel model var:

1. Doğrudan API (Kart Verisi Sunucunuzdan Geçer)

Kart numarası, son kullanma tarihi ve CVV sizin backend'inize POST edilir, siz bunu ödeme kuruluşuna iletirsiniz. En esnek ama en riskli yöntem — PCI DSS Seviye 1 gereksinimlerine tabi olabilirsiniz. Yüksek işlem hacmi olmayan siteler için önerilmez.

2. iFrame / Hosted Form

Kart formu ödeme kuruluşunun sunucusunda render edilir, sizin sayfanıza sadece bir iframe olarak gömülür. Kart verisi hiçbir zaman sizin sunucunuza uğramaz. PayTR'nin varsayılan modeli budur, iyzico'nun Checkout Form'u da benzer mantıkla çalışır.

3. Yönlendirmeli 3D Secure

Kullanıcı ödeme sayfasında formu doldurur, ardından bankanın 3D Secure sayfasına yönlendirilir, SMS/OTP doğrulaması yapılır ve sonuç callback URL'inize POST edilir. Param'ın klasik entegrasyon akışı bu şekildedir.

Büyükweb perspektifi: Kart verisinin sunucunuzdan hiç geçmediği iFrame veya hosted form modellerini tercih etmenizi öneriyoruz. Bu sadece güvenlik meselesi değil — PCI DSS uyumluluk kapsamınızı (SAQ A vs SAQ D) doğrudan belirliyor ve denetim maliyetinizi düşürüyor. Konuyu detaylı incelemek isterseniz e-ticaret güvenliği, SSL ve PCI DSS uyumluluğu yazımıza bakabilirsiniz.

Adım Adım Entegrasyon Süreci

Her üç sağlayıcının da genel akışı benzer: API anahtarı al, ödeme isteği oluştur, kullanıcıyı ödeme sayfasına yönlendir/formu göster, callback'i doğrula, siparişi güncelle. Aşağıda temel iskeleti gösteren örnekler var (gerçek üretim kodu için ilgili sağlayıcının güncel dokümantasyonunu kullanın).

iyzico — Ödeme İsteği Oluşturma (PHP)

require 'vendor/autoload.php';

$options = new \Iyzipay\Options();
$options->setApiKey('sandbox-api-anahtariniz');
$options->setSecretKey('sandbox-secret-anahtariniz');
$options->setBaseUrl('https://sandbox-api.iyzipay.com');

$request = new \Iyzipay\Request\CreateCheckoutFormInitializeRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setConversationId('siparis-1234');
$request->setPrice('120.50');
$request->setPaidPrice('120.50');
$request->setCurrency(\Iyzipay\Model\Currency::TL);
$request->setBasketId('sepet-1234');
$request->setPaymentGroup(\Iyzipay\Model\PaymentGroup::PRODUCT);
$request->setCallbackUrl('https://siteniz.com/odeme/donus');

$checkoutFormInitialize = \Iyzipay\Model\CheckoutFormInitialize::create($request, $options);
echo $checkoutFormInitialize->getPaymentPageUrl();

Callback URL'e dönen token parametresi ile CheckoutForm::retrieve() çağrısı yapılarak işlem sonucu doğrulanır. Bu doğrulama adımını atlamak, güvenlik açısından en sık yapılan hatadır — asla sadece tarayıcı yönlendirmesine güvenmeyin, sunucudan sunucuya doğrulama şart.

PayTR — Token Oluşturma ve Hash Doğrulama (PHP)

$merchant_id = 'MAGAZA_NO';
$merchant_key = 'MAGAZA_ANAHTARI';
$merchant_salt = 'MAGAZA_SALT';

$user_ip = $_SERVER['REMOTE_ADDR'];
$merchant_oid = 'siparis' . time();
$email = $_POST['email'];
$payment_amount = 12050; // kuruş cinsinden
$user_basket = base64_encode(json_encode([['Ürün', '120.50', 1]]));

$hash_str = $merchant_id . $user_ip . $merchant_oid . $email . $payment_amount . $user_basket . '0' . '0' . 'TL' . '1';
$paytr_token = base64_encode(hash_hmac('sha256', $hash_str . $merchant_salt, $merchant_key, true));

PayTR'nin callback'ini işlerken gelen hash değerini kendi tarafınızda tekrar hesaplayıp karşılaştırmadan siparişi "ödendi" olarak işaretlemeyin. Hash doğrulanmadan işlem onaylanırsa, sahte callback isteklerine karşı sisteminiz savunmasız kalır.

Param — 3D Secure Model Talebi (özet akış)

// 1. Sipariş oluşturulur, tutarı ve dönüş URL'leri belirlenir
$params = [
    'G' => ['CLIENT_CODE' => '...', 'CLIENT_USERNAME' => '...', 'CLIENT_PASSWORD' => '...'],
    'GUID' => '...',
    'KK_Sahibi' => $_POST['kart_sahibi'],
    'KK_No' => $_POST['kart_no'],
    'Islem_Tutar' => '120,50',
    'Toplam_Tutar' => '120,50',
    'Basarili_URL' => 'https://siteniz.com/odeme/basarili',
    'Hata_URL' => 'https://siteniz.com/odeme/hata',
];
// 2. SOAP client ile TP_WMD_UCD metoduna istek atılır
// 3. Dönen 3D Secure formu kullanıcıya gösterilir, işlem callback ile tamamlanır

Param'ın SOAP tabanlı eski API'si biraz daha fazla boilerplate gerektiriyor; hazır bir SDK kullanmak (resmi GitHub deposundaki örnekler) elle SOAP envelope yazmaktan daha güvenilir.

Büyükweb notu: Hangi sağlayıcıyı seçerseniz seçin, callback endpoint'inizin her zaman HTTPS üzerinden erişilebilir, doğru sertifikaya sahip ve dış dünyadan gelen POST isteklerini engelleyecek bir güvenlik duvarı kuralı ile bloklanmamış olması gerekiyor. Bu, entegrasyon test aşamasında en sık karşılaşılan "callback gelmiyor" sorununun kaynağıdır.

3D Secure, Güvenlik ve PCI DSS Uyumluluğu

3D Secure (3DS), kart sahibinin bankası tarafından ek doğrulama (SMS OTP, mobil bildirim) istenmesini sağlayan katmandır ve chargeback riskini büyük ölçüde satıcıdan bankaya devreder. Üç sağlayıcı da 3DS destekliyor; iyzico ve Param'da opsiyonel/zorunlu seçilebilirken PayTR'de iFrame akışı zaten 3DS'i varsayılan olarak içeriyor.

Teknik olarak dikkat edilmesi gerekenler:

• SSL/TLS zorunlu: Ödeme sayfanız ve callback endpoint'iniz geçerli bir SSL sertifikası olmadan çalışmaz; sağlayıcılar HTTPS olmayan callback URL'lerini genelde reddeder.
• PCI DSS kapsamı: Kart verisi sunucunuzdan hiç geçmiyorsa (iFrame/hosted form) genelde SAQ A veya SAQ A-EP kapsamına girersiniz — yıllık öz değerlendirme yeterli olabilir. Kart verisi sunucunuzdan geçiyorsa SAQ D gibi çok daha kapsamlı bir denetim süreci gerekir.
• Loglama disiplini: Kart numarası, CVV gibi hassas verileri hiçbir koşulda log dosyalarına, hata izleme araçlarına veya veritabanına düz metin olarak yazmayın. Bu hem yasal hem teknik bir zorunluluk.
• Rate limiting: Ödeme endpoint'lerinize art arda otomatik istek atılmasını (kart deneme saldırıları / carding) engellemek için IP bazlı hız sınırlama uygulayın.

Mevzuat tarafında da mesafeli satış sözleşmesi ve kişisel veri işleme yükümlülükleri devreye giriyor; bu konuyu e-ticarette KVKK, GDPR ve mesafeli satış sözleşmesi yazımızda ayrıca ele aldık.

Sunucu Altyapısı: Sanal POS Entegrasyonunda Performans ve Güvenlik

Sanal POS entegrasyonu kod kadar sunucu konfigürasyonuna da bağlıdır. Aşağıdaki noktalar entegrasyon sürecinde sık gözden kaçar:

• Giden bağlantı kısıtlamaları: Ödeme kuruluşunun API sunucularına giden isteklerinizi engelleyen bir güvenlik duvarı kuralı varsa, ödeme isteği zaman aşımına uğrar. Sunucunuzun ilgili sağlayıcının API domainlerine outbound erişimi olduğundan emin olun.
• PHP zaman aşımı ayarları: 3D Secure doğrulama ve callback bekleme süreleri bazen 20-30 saniyeyi bulabiliyor; max_execution_time ve HTTP client timeout değerlerinizi buna göre ayarlamanız gerekir.
• Sabit IP ihtiyacı: Bazı sağlayıcılar (özellikle kurumsal anlaşmalarda) callback veya API erişimini belirli IP'lerden kısıtlayabiliyor. Paylaşımlı hosting'te IP değişkenlik gösterebilir; bu durumda sabit ve size özel bir IP'ye sahip olmak entegrasyonu kolaylaştırır.
• Yoğun trafik anlarında stabilite: Kampanya dönemlerinde eşzamanlı ödeme isteği sayısı artınca, kaynak paylaşımlı barındırma yavaşlayabilir ve callback'lerin zamanında işlenmemesi siparişlerin "ödendi" durumuna geçmemesine yol açabilir.

Bu nedenle, özellikle orta-yüksek trafikli e-ticaret siteleri için kaynakları kendinize ayrılmış, sabit IP'li bir sunucu tercih etmek entegrasyonun güvenilirliğini artırır. E-Ticaret VDS paketlerimiz, tam da bu ihtiyaç için tasarlandı: kaynaklar başka sitelerle paylaşılmıyor, günlük otomatik yedekleme dahil, panel kurulumu (cPanel/Plesk) VDS üzerinde ücretsiz sağlanıyor.

Büyükweb notu: Sanal POS entegrasyon testlerinde en sık gördüğümüz sorun, callback'lerin paylaşımlı hosting ortamında ara sıra "kayıp" gitmesi. Kaynak kısıtlı ortamlarda PHP-FPM worker'ları dolduğunda gelen POST istekleri kuyrukta bekliyor, bazen zaman aşımına uğruyor. Kendi kaynaklarınıza sahip bir VDS'te bu risk büyük ölçüde ortadan kalkıyor.

Entegrasyon sonrası performansı izlemeyi de ihmal etmeyin — ödeme akışındaki bir aksaklık genelde önce uptime/hata takip araçlarında görünür; bu konuda e-ticaret performans izleme, uptime ve hata takibi (APM) yazımız pratik bir başlangıç noktası sunuyor.

Sık Yapılan Hatalar ve Çözümleri

1. Callback doğrulamasını atlamak: Sadece tarayıcı yönlendirmesine (redirect URL) bakıp siparişi "ödendi" işaretlemek, sahte işlem riskini açık bırakır. Her zaman sunucudan sunucuya (server-to-server) callback/hash doğrulaması yapın.

2. Test ve canlı ortam anahtarlarını karıştırmak: Sandbox API anahtarlarıyla canlı ortamda test yapmaya çalışmak ya da tam tersi, entegrasyonun en klasik hatasıdır. Ortam değişkenlerini (.env) net ayırın.

3. Tutar birimini yanlış göndermek: PayTR kuruş cinsinden (100 kat), iyzico ve Param virgüllü TL formatında tutar bekliyor. Bu formatları karıştırmak "yanlış tutar tahsil edildi" şikayetlerine yol açar.

4. Webhook/callback URL'i yayına almadan test etmemek: Yerel geliştirme ortamında (localhost) callback test edilemez; tünel araçlarıyla veya staging sunucusunda gerçek URL üzerinden test şarttır.

5. Taksit/komisyon oranlarını sabit kodlamak: Sağlayıcıların komisyon ve taksit oranları zaman içinde değişebilir; bu bilgileri API üzerinden dinamik sorgulamak, sabit kodlamaktan daha sağlıklıdır.

Sıkça Sorulan Sorular

iyzico, PayTR ve Param'dan hangisi daha kolay entegre edilir?

Genel geliştirici deneyimine göre iyzico, çok dilde resmi SDK ve daha net dokümantasyon sunduğu için genelde en hızlı entegre edilen seçenek olarak öne çıkıyor. PayTR'nin iFrame modeli de görece basit. Param'ın SOAP tabanlı eski API'si biraz daha fazla efor gerektirebilir, ancak resmi örnek kodlarla bu fark kapanıyor.

Kart bilgilerini kendi veritabanımda saklayabilir miyim?

Önerilmez. Kart numarası ve CVV gibi verileri saklamak PCI DSS'in en üst seviye gereksinimlerini tetikler. Bunun yerine sağlayıcıların sunduğu "kart saklama" (tokenization) servislerini kullanın — kart verisi sağlayıcıda tokenize edilir, sizde sadece bir token kalır.

3D Secure'u kapatıp doğrudan ödeme alabilir miyim?

Teknik olarak bazı sağlayıcılarda opsiyonel olarak kapatılabiliyor, ancak 3DS'siz işlemlerde chargeback (ters ibraz) riski satıcıya kalıyor ve bankalar bu tür işlemlerde ek risk skorlaması uygulayabiliyor. Özellikle yeni açılan mağazalar için 3D Secure'u açık tutmak öneriliyor.

Callback URL'im HTTPS olmak zorunda mı?

Evet, üç sağlayıcı da güvenlik gereği HTTPS callback URL'i talep ediyor. Geçerli ve güncel bir SSL sertifikası olmadan entegrasyon testleri genelde başarısız olur.

Aynı sitede birden fazla sanal POS sağlayıcısı kullanabilir miyim?

Evet, teknik olarak mümkün — bazı e-ticaret siteleri yedeklilik için birincil sağlayıcı devre dışı kaldığında ikinci bir sağlayıcıya otomatik geçiş yapan mantık kuruyor. Bu, ekstra entegrasyon ve test yükü getirir ama yüksek hacimli sitelerde tercih edilebilir.

Sanal POS entegrasyonu için VDS mi paylaşımlı hosting mi daha uygun?

Düşük trafikli, test aşamasındaki siteler için paylaşımlı hosting yeterli olabilir. Ancak kampanya dönemlerinde yüksek eşzamanlı işlem hacmi bekleniyorsa, kaynakları paylaşılmayan ve sabit IP'li bir VDS ortamı callback güvenilirliği ve genel stabilite açısından daha sağlıklı bir tercih.

Test (sandbox) ortamından canlıya geçerken nelere dikkat etmeliyim?

API anahtarlarını, callback URL'lerini ve varsa IP kısıtlama listelerini canlı ortama göre güncelleyin; ayrıca gerçek bir kartla küçük tutarlı uçtan uca bir test işlemi yaparak callback'in doğru şekilde sipariş durumunu güncellediğini doğrulayın.

Büyükweb Hizmetleri

Sanal POS entegrasyonunuzun stabil çalışması için kaynakları size özel, sabit IP'li ve günlük otomatik yedeklemeli bir altyapı arıyorsanız:

• E-Ticaret VDS

Sorularınız için 0850 302 60 70 numaralı satış öncesi destek numaramızdan bize ulaşabilir veya iletişim sayfası üzerinden yazabilirsiniz.