PayTR Sanal POS Entegrasyonu Nasıl Yapılır? (2026 Teknik Rehber)

PayTR Sanal POS Nedir?

PayTR, Türkiye'nin önde gelen ödeme altyapısı sağlayıcılarından biridir. Sanal POS hizmeti, e-ticaret sitenizdeki müşterilerin kredi kartıyla ödeme yapmasına olanak tanır.

PayTR entegrasyonunda iki temel yöntem vardır:

1. iFrame API – PayTR'nin ödeme formunu kendi sitenize gömer
2. Direkt API – Kart bilgileri kendi formunuzda alınır, PayTR'ye iletilir (PCI-DSS gerektirir)

Çoğu e-ticaret sitesi için iFrame API tercih edilir; karmaşıklığı düşük ve PCI uyumluluk yükü PayTR'dedir.

Entegrasyon Öncesi Gereksinimler

1. PayTR hesabı açın: paytr.com → Üye İşyeri Başvurusu
2. Başvuru onaylandıktan sonra Merchant ID, Merchant Key, Merchant Salt alırsınız
3. SSL sertifikası zorunludur (HTTPS)
4. Test ortamı için www.paytr.com/odeme/test kullanılır

iFrame API Entegrasyon Adımları

1. Token Oluşturma (Backend)

// PHP örneği
$merchant_id = 'XXXXXX';
$merchant_key = 'XXXXXXXXX';
$merchant_salt = 'XXXXXXXXX';

$user_ip = $_SERVER['REMOTE_ADDR'];
$merchant_oid = 'siparis-' . time(); // Benzersiz sipariş ID
$email = 'musteri@email.com';
$payment_amount = 10000; // Kuruş cinsinden (100 TL = 10000)
$currency = 'TL';
$no_installment = 0; // 0 = taksit açık
$max_installment = 0; // 0 = bankaya bırak

// Token hash'i
$hash_str = $merchant_id . $user_ip . $merchant_oid . $email 
          . $payment_amount . $currency . $no_installment 
          . $max_installment . $merchant_salt;
$paytr_token = base64_encode(hash_hmac('sha256', $hash_str, $merchant_key, true));

// PayTR API'ye POST isteği
$post_vals = [
  'merchant_id' => $merchant_id,
  'user_ip' => $user_ip,
  'merchant_oid' => $merchant_oid,
  'email' => $email,
  'payment_amount' => $payment_amount,
  'paytr_token' => $paytr_token,
  'user_basket' => base64_encode(json_encode($basket)),
  // ... diğer alanlar
];

2. iFrame Token Alma

POST https://www.paytr.com/odeme/api/get-token
→ Yanıt: { "status": "success", "token": "XXXXX" }

3. iFrame Gösterme (Frontend)

<script src="https://www.paytr.com/js/iframeResizer.min.js"></script>
<iframe src="https://www.paytr.com/odeme/guvenli/TOKEN_BURAYA"
        id="paytriframe" frameborder="0" scrolling="no"
        style="width:100%;"></iframe>
<script>iFrameResize({}, '#paytriframe');</script>

4. Callback (Ödeme Bildirimi)

PayTR, ödeme sonucunu sitenizin bildirim URL'sine POST eder:

POST https://siteniz.com/paytr-callback
→ merchant_oid, status ("success"/"fail"), total_amount, hash

Callback'te hash doğrulaması yapın:

hash = base64(hmac_sha256(merchant_oid + merchant_salt + status, merchant_key))

Test Kartları

PayTR test ortamında kullanabileceğiniz kart:

• Kart No: 4355 0843 5508 4358
• SKT: 12/26
• CVV: 000
• 3D Şifre: 123456

Sık Yapılan Hatalar

Hash hatalı: En yaygın sorun. Hash hesaplarken field sırası ve encoding önemli. PayTR dokümantasyonundaki sırayı birebir takip edin.

Callback URL ulaşılamıyor: Test sırasında localhost callback URL'si çalışmaz. ngrok veya canlı ortam kullanın.

Çift ödeme kaydı: Callback birden fazla kez gelebilir. merchant_oid bazında idempotency kontrolü ekleyin.

SSL hatası: HTTPS zorunludur. Self-signed sertifika çalışmaz, üretim sertifikası kullanın.

Tutar format hatası: payment_amount kuruş cinsindendir. 100 TL için 10000 girilmelidir.

Taksit Entegrasyonu

no_installment = 0  // Taksit açık
max_installment = 9 // Maksimum 9 taksit

Belirli bankaları kısıtlamak için installment_filter parametresi kullanılır.

WooCommerce ve Shopify Entegrasyonu

Özel geliştirme yerine hazır eklenti kullanmak isteyenler için:

• WooCommerce: PayTR resmi WooCommerce eklentisi (ücretsiz, GitHub'da)
• Shopify: PayTR Shopify uygulaması (Shopify App Store'da)
• OpenCart, PrestaShop: Resmi modüller mevcut

Sık Sorulan Sorular

PayTR entegrasyonu ücretsiz mi? Entegrasyon ücretsiz. Komisyon yalnızca gerçekleşen işlemler üzerinden alınır (%1.49 + KDV ve üzeri, sözleşmeye göre değişir).

3D Secure zorunlu mu? 2026 itibarıyla 3D Secure çoğu işlemde zorunludur. iFrame entegrasyonunda 3D Secure PayTR tarafından yönetilir.

PayTR'yi test etmek için canlı hesap şart mı? Hayır. Başvuru onaylanmadan önce sandbox ortamında test yapılabilir.

Sonuç

PayTR sanal POS entegrasyonu, doğru adımlar izlendiğinde birkaç günde tamamlanabilir. iFrame API, güvenlik sorumluluğunu PayTR'ye bıraktığı için küçük ve orta ölçekli işletmeler için en uygun yoldur.

Ödeme sistemi entegrasyonunu sizin için kurmamızı ister misiniz? Moyduz olarak PayTR, İyzico ve diğer tüm ödeme sistemlerinin entegrasyonunu e-ticaret sitenize kuruyoruz. Ücretsiz görüşme için iletişime geçin.