Webhook
Ödeme ve iade sonuçlarını sunucunuza bildirir. Kullanıcı tarayıcıyı kapatsa bile sonucu almanın güvenilir yolu budur.
Kurulum
TahsilatE panelinde, Merchant API menüsü altındaki Webhook Hedefleri bölümünden en fazla 3 adres tanımlayabilirsiniz. Her olay tanımlı tüm adreslere POST ile, JSON gövdeyle gönderilir. Adres olarak https kullanın.
Ödeme sayfası oturumu açarken callbackUrl verirseniz, o oturumun ödemeleri bu adrese de gönderilir. Eklentiler gibi her mağazanın kendi adresini bildirdiği entegrasyonlar için panel tanımı gerekmez.
Olaylar
| Ad | Açıklama |
|---|---|
| payment.completed | Bir ödeme sonuçlandığında gönderilir (SUCCESSFUL, FAILED veya PENDING). API ile başlatılmayan ödemeleriniz (panel, ödeme linki) için de gönderilir. |
| refund.completed | Bir iade tamamlandığında (SUCCESSFUL) veya bankaya iletildiğinde (PENDING) gönderilir. |
| webhook.test | Yalnızca test ortamında, Profil sayfasındaki "Test bildirimi gönder" ile gönderilir. Gövdede message ve sentAt vardır; imza doğrulamanızı denemek içindir. |
Header'lar
| Ad | Açıklama |
|---|---|
| X-Webhook-Event | Olay adı: payment.completed veya refund.completed. |
| X-Webhook-Id | Bildirimin kimliği. Tekrar denemelerde aynı kalır; aynı bildirimi iki kez işlememek için kullanın. |
| X-Webhook-Attempt | Kaçıncı deneme olduğu (1'den başlar). |
| X-Timestamp | İmzanın oluşturulduğu an (Unix saniye). Her denemede yenilenir. |
| X-Signature | HMAC-SHA256(X-Timestamp + "." + ham gövde, secretKey), küçük harfli hex. |
İmza Doğrulama
Her bildirimde imzayı JSON'u parse etmeden, ham gövde üzerinden doğrulayın. Eski bildirimlerin tekrar oynatılmasını önlemek için zaman damgası 5 dakikadan eskiyse isteği reddedin.
Webhook Doğrulama
Ham gövde, zaman damgası ve sabit zamanlı karşılaştırma
TypeScriptTeslimat ve Tekrar Deneme
2xx dışındaki her cevap ve bağlantı hatası tekrar denenir.
| Ad | Açıklama |
|---|---|
| 1. deneme | Olay anında |
| Tekrar denemeler | 1 dk, 5 dk, 15 dk, 1 saat, 3 saat, 6 saat, 12 saat ve 24 saat sonra (toplam yaklaşık 2 gün) |
| Başarılı sayılan | 2xx HTTP durum kodu. Yönlendirmeler (3xx) takip edilmez ve başarısız sayılır. |
| Zaman aşımı | 10 saniye |
payment.completed Gövdesi
| Ad | Açıklama |
|---|---|
| transactionId | İşlem ID'si. |
| amount | Ödeme tutarı. |
| status | SUCCESSFUL, FAILED veya PENDING. |
| installment | Taksit sayısı. |
| netAmount | Hesabınıza geçecek net tutar. |
| resultMessage | Banka sonuç mesajı. |
| description | Ödeme açıklaması. |
| date | Ödemenin oluşturulma zamanı (ISO 8601). |
| bankName / cardProgramName | Kartın bankası ve programı (bilinmiyorsa null). |
| maskedCardNumber | Maskeli kart numarası. |
| customer / items | API ile başlatılan ödemelerde, istekte gönderdiğiniz müşteri ve sepet bilgileri. |
| orderId / checkoutToken | Ödeme sayfası (checkout) ile alınan ödemelerde siparişin numarası ve oturumun token'ı. |
Örnek payment.completed
refund.completed Gövdesi
| Ad | Açıklama |
|---|---|
| transactionId | İade edilen ödemenin işlem ID'si. |
| amount | İade tutarı. |
| status | SUCCESSFUL veya PENDING. |
| merchantId | Üye işyeri ID'si. |
| orderId | Ödeme sayfası (checkout) ile alınan ödemelerde siparişin numarası. |
