PayTR bildirim URL nedir?

Ödemenin başarılı olduğu halde sipariş sisteminde onay görünmüyorsa veya bildirimlerin gidişatı kafanı karıştırıyorsa, PayTR bildirim URL yapılandırması ve doğrulaması büyük ihtimalle sorunun kaynağıdır.

PayTR bildirim URL nedir ve neden kritik?

PayTR bildirim URL, ödeme tamamlandığında PayTR sunucularının senin sunucuna gönderdiği HTTP POST çağrısıdır. Bu çağrı, sipariş numarası (merchantoid), ödeme durumu (status), ödeme tutarı (totalamount) ve doğrulama için bir hash gibi alanlar içerir. Amacı, ödeme sağlayıcısından gelen sonucu anında alıp siparişi güncellemek ve müşteriye doğru bilgi vermektir. OWASP’ın webhook güvenliği rehberi ve PCI DSS standartları, ödeme bildirimlerinin doğrulanmasını ve güvenli kanallardan alınmasını zorunlu sayar; bu yüzden bildirim URL’sini doğru yapılandırmak hem iş akışının hem de uyumluluğun temelidir.

Bildirim akışı: adım adım nasıl çalışır

1. Müşteri ödeme formunu doldurur ve PayTR ödeme sayfasına yönlendirilir veya iframe içinde ödeme yapar.
2. Ödeme tamamlandığında PayTR, önceden tanımladığın bildirim URL’sine POST isteği atar.
3. Senin sunucun, gelen verinin gerçek PayTR’den geldiğini doğrular.
4. Doğrulama başarılıysa sipariş durumunu değiştirir, faturayı oluşturur veya stok güncellemesi yaparsın.
5. Sunucun PayTR’ye genellikle “OK” veya belirlenen başarı yanıtını gönderir; aksi halde PayTR tekrar deneme yapabilir.

Doğrulama ve güvenlik: uygulaman gereken adımlar

– HTTPS zorunlu kullan: Bildirim URL’si mutlaka TLS ile korunmuş olmalı.
– IP/agent kontrolü: PayTR’nin IP aralığını mümkünse beyaz listeye al; ancak IP tek başına güvenlik sağlamaz.
– Sipariş kontrolü: merchantoid ile veritabanında siparişi bul ve totalamount ile ödeme tutarını karşılaştır.
– Tekrarlı işlemleri önle: Aynı merchantoid için idempotent işlem uygula; iki kez ödeme onayı alırsan kayıtları ikiye katlama.
– Hash doğrulama: PayTR gönderdiği hash ile isteğin bütünlüğünü sağlar. PayTR dokümantasyonunda önerilen doğrulama mantığı genelde şu kalıba dayanır: gönderilen hash’i, senin sahip olduğun merchantsalt veya secret ile aynı algoritmayla yeniden üret ve karşılaştır. OWASP, webhook’larda HMAC-SHA256 gibi güçlü imzalama yöntemlerini kullanmanı tavsiye eder. PCI DSS ise ödeme verilerini doğrularken hassas bilgilerin sunucunda saklanmasına dikkat etmeni ister.

Örnek (kavramsal) PHP doğrulama mantığı:
$payloadMerchantOid = $POST[‘merchantoid’];
$payloadStatus = $POST[‘status’];
$payloadAmount = $POST[‘totalamount’];
$receivedHash = $POST[‘hash’];
$secret = ‘MERCHANTSALT’;
$calculated = base64encode(hashhmac(‘sha256’, $payloadMerchantOid.$payloadStatus.$payloadAmount, $secret, true));
if ($calculated === $receivedHash) { // güvenli kabul et } else { // reddet }

Yıllar süren ödeme entegrasyonları takibim gösteriyor ki, en sık görülen sorunlar doğru endpoint’in kaydedilmemesi, hash algoritmasının yanlış uygulanması ve HTTPS sertifika sorunları oluyor. Kendi tecrübemle söyleyebilirim ki, geliştiriciler genelde şu hataları yapıyor: 1) test hesapları için farklı merchantsalt kullanıp production’da onu değiştirmeyi unutmak, 2) gelen POST içeriğini raw olarak okumayıp uygulama framework’ünün body-parser’ı yüzünden hash hesaplamakta hata yapmak, 3) eşzamanlı isteklerde veritabanı kilitlenmesi yüzünden sipariş durumunu iki kere güncellemek.

Hızlı hata ayıklama adımları:
– PayTR panelinde bildirim geçmişini kontrol et; gönderim hatası veya 4xx/5xx kodları gözlemle.
– Sunucunda access/error loglarını incele; POST payload, header ve time-stamp bilgilerini kaydet.
– Hash hesaplama aşamasında encoding farklarını kontrol et (UTF-8, base64 true/false bayrağı gibi).
– Test ortamında Postman veya ngrok ile gelen isteği taklit edip yerel sunucuda doğrula.
– Sunucu yanıtını 200 OK yerine doğru içerikle dön; bazı sağlayıcılar içerik bekler.

Güvenlik için pratik uygulamalar:
– Bildirim endpoint’ine rate limit uygula.
– Sadece ihtiyaç duyulan alanları kaydet; kart numarası gibi hassas verileri saklama.
– Kritik işlemleri (sipariş tamamlama) veritabanı transaction içinde yap; hata durumunda rollback uygula.
– PayTR geliştirici dokümanını düzenli kontrol et; sağlayıcı API değişiklikleri olabiliyor.

Sıkça Sorulan Sorular

PayTR bildirim URL nasıl kaydedilir?

PayTR yönetim panelinde veya entegrasyon sırasında merchant ayarlarına bildirim URL’ini girersin; test ve canlı URL’lerini ayrı tut.

Bildirim gelmiyorsa ilk nereden başlamalıyım?

PayTR panelindeki gönderim geçmişini kontrol et, ardından sunucu log’larına bak; sertifika veya DNS sorunları sık görülen nedenlerdir.

Hash doğrulaması neden yanlış çıkıyor?

Genelde secret/merchantsalt yanlış, encoding farklı veya hash algoritması hatalı kullanıldığında olur. Dokümandaki örneğe birebir uyarak yeniden kontrol et.

İdempotent mantık uygula: aynı merchantoid için ikinci işleme izin verme; database’de durum kontrolü ile işlemi atla.

Bildirim URL’si herkese açık mı olmalı?

URL internete açık olmalı ki PayTR erişebilsin, ancak endpoint’i güvenlik önlemleriyle koru (HTTPS, IP filtreleme, HMAC doğrulama).

En çok merak ettiğin doğrulama adımı hangisiydi? PayTR bildirim URL’inle ilgili yaşadığın spesifik problemi veya hata mesajını paylaş, birlikte adım adım çözüm bulalım.

Not: Örnek kodlar ve doğrulama mantığı genel endüstri uygulamalarına dayanır; kesin uygulama için PayTR’nin resmi geliştirici dokümanını ve API referansını kullan. Bitkisel Diyar’ın ödeme entegrasyon rehberleri de uygulamada işine yarayacak pratik örnekler içerir.