PayTR Sanal POS Entegrasyonu: Hash Hatası 3 Saat Bulunmadı — Gerçek Sorunlar (2026)

PayTR Sanal POS Nedir?

PayTR entegrasyonunu 3 saatte tamamlamayı planlamıştık. 8 saat sürdü. Sorun kod yapısında değildi — hash hesaplamada field sırası PayTR dokümantasyonundaki örnekten farklıydı. Bu tek satır fark, token doğrulamasını tamamen bloke etti ve hata mesajı sadece "geçersiz token" diyordu.

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ç

Gerçek Senaryo: Hash Hatası 3 Saat Bulunmadı

Bir müşterimiz için PayTR iFrame entegrasyonunu kurduk. Token oluşturma kodu yazıldı, test endpoint'e gönderildi — her seferinde "geçersiz token" hatası.

Kodu satır satır inceledik. Parametreler doğruydu. Değerler doğruydu. Encoding doğruydu.

3 saat sonra bulduğumuz şey:

Hash hesaplamada field sırası yanlıştı. PayTR dokümantasyonunda örnek kod farklı bir sıra kullanıyordu — ve merchant_id ile user_ip'nin sırası değişince hash tamamen farklı çıkıyordu.

Düzeltme: 1 satır. Süre: 3 dakika.

Bu yüzden PayTR entegrasyonunda en sık yapılan hata kod hataları değil — dokümantasyonu dikkatli okumamak.

Kaçınmak için: hash hesaplamayı ayrı bir fonksiyona alın, PayTR'nin resmi dokümantasyonundaki field sırasını kopyalayın ve test kartıyla her adımı ayrı ayrı doğrulayın.

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.

İlgili Sayfalar

• Hub: E-Ticaret Rehberi
• E-Ticaret Altyapısı
• Karşılaştırma Tablosu
• Ücretsiz Teklif Alın →

Sıkça Sorulan Sorular

Soru: Bu içerik kimler için uygundur? Cevap: Konuyla ilgili karar verecek ekipler için hızlı bir referans sağlar.