Webhooks

Genel Bakış

PayTR, ödeme sonucunu sunucunuza POST /api/billing/webhook isteğiyle bildirir. Handler otomatik olarak hem ilk ödeme hem de tekrarlayan ödeme webhook'larını ayırt eder.

HMAC-SHA256 Doğrulama

Her webhook imzalıdır. Handler imzayı otomatik doğrular — geçersizse isteği reddeder.

Hash parametreleri:
  merchant_oid + merchantSalt + status + total_amount
  → base64( HMAC-SHA256( hashStr, merchantKey ) )

timingSafeEqual() ile karşılaştırılır → timing saldırısı koruması

Webhook Türlerini Ayırt Etme

merchant_oid Prefix	Tür	İşleyici
`DC...`	İlk ödeme (Direct API)	`PendingCheckout` lookup → `manager.activate()`
`BP...`	Tekrarlayan ödeme (Cron)	`manager.handleWebhookResult()`

Test Modu Farkları

PayTR test modu webhook payload'ında bazı alanları göndermez:

Alan	Production	Test Modu
`email`	Dahil	Dahil değil — `PendingCheckout`'tan alınır
`utoken`	Dahil (başarılı ilk ödemede)	Dahil değil — boş string saklanır
`currency`	`"TRY"`	`"TL"` — otomatik normalize edilir

Handler tüm test modu farklılıklarını otomatik olarak yönetir. Kodunuzda özel bir işlem yapmanıza gerek yoktur.

"OK" Zorunluluğu

PayTR, webhook handler'ın her zaman "OK" plain text döndürmesini bekler — hata durumlarında bile. Bu yanıtı almazsa webhook'u yeniden gönderir.

Handler bunu otomatik olarak sağlar.