WooCommerce PayTR Entegrasyonu: Adım Adım Kurulum ve Hata Çözümleri

Kısaca

Kurulum dört adımdan oluşur: PayTR panelinden mağaza numarası, mağaza parolası ve gizli anahtarı almak, WooCommerce’a PayTR eklentisini kurmak, bu üç bilgiyi eklenti ayarlarına girmek ve PayTR paneline bildirim adresini tanımlamak. Sonrasında test modunda uçtan uca bir sipariş denenir. Üye iş yeri hesabınız henüz yoksa önce sanal POS başvuru sürecine bakın.

Kurulumların çoğu ilk üç adımda değil, dördüncüde takılır. “Ödeme başarılı ama sipariş beklemede kalıyor” şikâyetinin arkasında neredeyse her zaman bildirim adresi sorunu vardır.

Kurulum adımları

1. Ön koşulları doğrulayın. Sitede geçerli bir SSL sertifikası olmalı ve tüm sayfalar HTTPS üzerinden açılmalı. WooCommerce para birimi Türk Lirası olmalı. Kalıcı bağlantı yapısında yazı adı veya benzeri bir seçenek önerilir; bazı eklentiler bildirim adresini bu yapı üzerinden üretiyor. Eklentinin verdiği adresi tarayıcıdan açıp yanıt aldığınızı doğrulayın. Bu üç madde, WooCommerce site kurulumunun standart ön koşullarıdır.

2. PayTR panelinden bilgileri alın. Üye iş yeri panelinde Bilgi ya da API bölümünde üç değer bulunur: Mağaza No, Mağaza Parola, Mağaza Gizli Anahtar. Üçünü kopyalarken baş ve sondaki boşluğa dikkat edin. Kopyalama sırasında araya giren tek bir boşluk karakteri, imza doğrulama hatasının en sık sebebi.

3. Eklentiyi kurun. PayTR’nin resmi WooCommerce eklentisini kurup etkinleştirin. Ardından WooCommerce, Ayarlar, Ödemeler yolunu izleyip PayTR yöntemini açın. Üç anahtarı girin, test modunu açık bırakın.

4. Bildirim adresini tanımlayın. Eklenti ayarlarında size bir bildirim (callback) adresi gösterilir. Bu adresi PayTR paneline girin. Bu adres, ödeme sonucunun sunucudan sunucuya iletildiği yerdir. Tarayıcı yönlendirmesi ile karıştırılmamalı: kullanıcı ödeme sonrası sekmeyi kapatsa bile siparişin tamamlanması bu adrese bağlıdır.

5. Taksit ve ödeme ayarlarını yapın. Taksit seçenekleri, vade farkının kime yansıtılacağı ve maksimum taksit sayısı hem PayTR panelinde hem eklentide tanımlıdır. İkisinin çelişmediğinden emin olun.

6. Test edin, sonra canlıya alın. Test modunda PayTR’nin verdiği test kartlarıyla işlem yapın. Başarılı ve başarısız senaryoları ayrı ayrı deneyin. Canlıya geçtikten sonra küçük tutarlı gerçek bir işlem yapıp iade edin.

Sık karşılaşılan hatalar

Belirti	Sebep	Çözüm
Ödeme alınıyor, sipariş “beklemede” kalıyor	Bildirim adresi panelde tanımlı değil ya da yanlış	Adresi PayTR paneline girin, sonundaki eğik çizgiye dikkat edin
Bildirim geliyor ama işlenmiyor	Güvenlik duvarı ya da WAF isteği engelliyor	Sunucu loglarında 403 arayın, PayTR bildirim IP’lerine izin verin
PayTR aynı bildirimi tekrar tekrar gönderiyor	Sayfa düz “OK” yanıtı dönmüyor	Tema veya eklentiden gelen PHP uyarısı, BOM ya da boşluk çıktısını temizleyin
“Geçersiz istek” ya da imza hatası	Gizli anahtar yanlış kopyalanmış, sunucu saati kaymış	Anahtarları yeniden yapıştırın, sunucu saatini NTP ile senkronize edin
Ödeme ekranı hiç açılmıyor	İframe engelleniyor	Güvenlik eklentisinin X-Frame-Options ve CSP ayarlarını kontrol edin
Tutar uyuşmazlığı hatası	Kuruş yuvarlama ya da kargo/kupon farkı	Gönderilen tutarın kuruş cinsinden tam sayı olduğunu doğrulayın
Siparişler çift oluşuyor	Mükerrer bildirim korunmuyor	Sipariş durumu zaten tamamlanmışsa ikinci bildirimi yok sayın
Ödeme sayfasında sepet boş görünüyor	Önbellek eklentisi checkout sayfasını önbelleğe alıyor	Sepet, ödeme ve hesabım sayfalarını önbellek dışına alın
Localhost’ta test edilemiyor	Bildirim adresine dışarıdan erişilemiyor	Staging alan adı ya da tünel aracı kullanın
Yönlendirme sonrası oturum kayboluyor	Üçüncü taraf çerez kısıtı	Ödeme dönüşünde siparişi oturumdan değil, sipariş anahtarından okuyun

Bu tablodaki ilk üç satır, karşılaştığımız kurulum sorunlarının büyük çoğunluğunu oluşturuyor. Üçü de bildirim akışıyla ilgili ve üçü de sipariş yönetiminde aynı belirtiyi veriyor.

Bildirim akışını doğru anlamak

Sorunların çoğu, ödeme akışının iki ayrı yoldan ilerlediğinin bilinmemesinden kaynaklanıyor.

Birinci yol, kullanıcının tarayıcısı. Kart bilgisi girilir, 3D Secure ekranı gelir, işlem biter ve kullanıcı sitenize geri döner. Bu yol görseldir, sipariş durumunu belirlemez.

İkinci yol, sunucudan sunucuya bildirim. PayTR, ödeme sonucunu doğrudan sizin sunucunuza gönderir. Sipariş bu bildirime göre tamamlanır. Kullanıcı sekmeyi kapatsa, interneti kesilse ya da geri dön butonuna bassa bile bildirim gelir.

Bildirimi işlemeden önce imzasını doğrulayın. Bu adım isteğe bağlı değil. Bildirim uç noktanız internete açık bir adrestir; adresi bilen herkes oraya istek gönderebilir. PayTR gelen POST içinde bir hash değeri gönderir. Bu değeri kendi tarafınızda merchant_key ve merchant_salt ile yeniden üretip gelenle karşılaştırın. Eşleşmiyorsa isteği hiç işlemeyin.

Doğrulama yapılmadan yazılmış bir uç nokta, dışarıdan gönderilen sahte bir “ödeme başarılı” isteğiyle siparişi ödenmiş işaretler. Ürün kargoya çıkar, para hesabınıza hiç geçmez. Aşağıdaki mükerrer bildirim koruması bu senaryoyu engellemez; o ayrı bir sorunu çözer.

Sunucunuzun bu bildirime vereceği yanıt tek bir şey olmalı: gövdesinde sadece OK yazan bir yanıt. Tema dosyasındaki bir boşluk, bir PHP uyarısı ya da dosya başındaki görünmez BOM karakteri bu yanıtı bozar. PayTR yanıtı alamadığını düşünüp bildirimi tekrarlar. Kodunuz mükerrer bildirime karşı korumasızsa, aynı sipariş iki kez işlenir, stok iki kez düşer, iki fatura kesilir.

Korunma basit: bildirimi işlemeden önce siparişin durumuna bakın. Sipariş zaten tamamlanmışsa hiçbir şey yapmadan OK dönün.

Test ortamını doğru kurmak

Yerel makinede tam test yapılamaz, çünkü PayTR sizin bilgisayarınıza bildirim gönderemez. İki seçeneğiniz var: internete açık bir staging alan adı ya da yerel sunucuyu dışarı açan bir tünel aracı.

Test listesinde şunlar olmalı:

• Başarılı tek çekim
• Başarılı taksitli işlem
• Yetersiz bakiye ya da reddedilen kart
• 3D Secure ekranında iptal
• Ödeme ekranında zaman aşımı
• Ödeme sonrası tarayıcının kapatılması
• Aynı bildirimin ikinci kez gönderilmesi
• Panelden tam iade
• Panelden kısmi iade

Son üç maddeyi atlayan kurulumlar canlıda sorun çıkarır. Özellikle kısmi iade, WooCommerce tarafında stok ve fatura akışını da etkilediği için ayrıca denenmeli.

Canlıya geçerken kontrol edilecekler: test modu kapatıldı mı, bildirim adresi canlı alan adına göre güncellendi mi, hata ayıklama günlükleri kapatıldı mı, sipariş durum e-postaları doğru çalışıyor mu.

Sipariş durumlarını doğru eşleyin

WooCommerce’ın sipariş durumları ile ödeme sonucunun eşleşmesi, kurulumun gözden kaçan parçası.

Sağlıklı bir eşleme şöyle olur: ödeme başlatıldığında sipariş “beklemede”, başarılı bildirim geldiğinde “işleniyor”, kargoya verildiğinde “tamamlandı”, başarısız bildirimde “başarısız”. İade edildiğinde WooCommerce’ın kendi iade kaydı oluşturulur.

Sık yapılan hata, başarılı ödemede siparişi doğrudan “tamamlandı” durumuna almak. Bu durumda dijital ürün indirme bağlantısı hemen açılır, fiziksel üründe ise depo ekibi hangi siparişin hazırlanacağını göremez. Ayrıca fatura otomasyonunuz “tamamlandı” durumunu tetikleyici kullanıyorsa, kargo bilgisi henüz oluşmadan fatura kesilir. Tetikleyicinin kargo adımına bağlanması, e-arşiv fatura akışının sağlıklı çalışmasının şartıdır.

Stok düşümünün hangi durumda yapıldığını da kontrol edin. Ödeme tamamlanmadan stok düşen kurulumlarda, terk edilen sepetler stoğu boşuna kilitler.

Bakım tarafında unutulanlar

Kurulum bittiğinde iş bitmiyor. Zaman içinde şu üç şey kurulumu bozuyor:

Alan adı ya da sunucu değişikliği. Site taşındığında bildirim adresi eski alan adında kalır. Taşıma kontrol listenize bu maddeyi ekleyin.

Güvenlik eklentisi güncellemesi. Yeni bir sürüm, dışarıdan gelen POST isteklerini engelleyen bir kural getirebilir. Ödemeler bir sabah aniden beklemede kalmaya başlarsa ilk bakılacak yer burasıdır.

PHP sürüm yükseltmesi. Eklenti eski bir PHP sürümüne göre yazılmışsa uyarı üretmeye başlar, uyarı da bildirim yanıtını bozar. Sürüm yükseltmesi sonrası mutlaka bir test ödemesi yapın.

Bu üç senaryonun hiçbiri hata mesajı üretmez. Ödemeler alınmaya devam eder, siparişler sessizce beklemede birikir. Bu yüzden sipariş listesinde uzun süre beklemede kalan kayıtlar için basit bir uyarı kurmak, aylık ciroyu kurtaran türden bir önlemdir.

Sık sorulan sorular

PayTR eklentisi WooCommerce’ın yeni sürümleriyle uyumlu mu? Uyumluluk bilgisi eklenti sayfasında yayımlanır. Büyük WooCommerce sürüm geçişlerinden önce staging ortamda test edin, doğrudan canlıda güncellemeyin.

Sepette hem fiziksel hem dijital ürün varsa sorun olur mu? Ödeme tarafında sorun olmaz. Fatura ve kargo akışında ayrım yapmanız gerekir; dijital ürün için kargo satırı oluşmamalı.

Ödeme sayfasını kendi tasarımıma göre değiştirebilir miyim? İframe modelinde sınırlı ölçüde. Tam kontrol için doğrudan API modu gerekir, o da ek onaya tabidir ve PCI DSS sorumluluğunu size taşır. Çoğu işletme için gereksiz bir yük. Sağlayıcı kararını henüz vermediyseniz PayTR ile iyzico karşılaştırmasına bakabilirsiniz.

Sipariş notlarında ne aramalıyım? WooCommerce sipariş notları, gelen bildirimi ve sonucunu kaydeder. Bir sipariş beklemede kaldıysa ilk bakılacak yer sipariş notlarıdır: bildirim hiç gelmemiş mi, yoksa gelip reddedilmiş mi, orada görünür.

Test kartlarını nereden alacağım? PayTR üye iş yeri panelinde, test modu ayarlarının bulunduğu bölümde yayımlanır. Gerçek kart bilgisiyle test yapmayın.

---

Ödeme entegrasyonunda asıl iş, hata senaryolarının doğru yönetilmesi. E-ticaret web sitesi hizmetimiz kapsamında WooCommerce kurulumlarında bildirim akışını, mükerrer işlem korumasını ve iade senaryolarını test edilmiş halde teslim ediyoruz.