TahsilatE Logo
Geliştirici Ortamı

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.

Test ortamında webhook adreslerinizi Profil sayfasından tanımlarsınız; oradan bir test bildirimi de gönderebilirsiniz.

Olaylar

AdAçıklama
payment.completedBir ö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.completedBir iade tamamlandığında (SUCCESSFUL) veya bankaya iletildiğinde (PENDING) gönderilir.
webhook.testYalnı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

AdAçıklama
X-Webhook-EventOlay adı: payment.completed veya refund.completed.
X-Webhook-IdBildirimin kimliği. Tekrar denemelerde aynı kalır; aynı bildirimi iki kez işlememek için kullanın.
X-Webhook-AttemptKaçıncı deneme olduğu (1'den başlar).
X-Timestampİmzanın oluşturulduğu an (Unix saniye). Her denemede yenilenir.
X-SignatureHMAC-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

TypeScript logoTypeScript

Teslimat ve Tekrar Deneme

2xx dışındaki her cevap ve bağlantı hatası tekrar denenir.

AdAçıklama
1. denemeOlay anında
Tekrar denemeler1 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ılan2xx HTTP durum kodu. Yönlendirmeler (3xx) takip edilmez ve başarısız sayılır.
Zaman aşımı10 saniye
Aynı bildirim birden fazla kez gelebilir. X-Webhook-Id'yi saklayıp ikinci kez işlemeyin. Tanımadığınız bir transactionId gelirse yine 200 dönün; yoksa bildirim boşuna tekrar denenir.

payment.completed Gövdesi

AdAçıklama
transactionIdİşlem ID'si.
amountÖdeme tutarı.
statusSUCCESSFUL, FAILED veya PENDING.
installmentTaksit sayısı.
netAmountHesabınıza geçecek net tutar.
resultMessageBanka sonuç mesajı.
descriptionÖdeme açıklaması.
dateÖdemenin oluşturulma zamanı (ISO 8601).
bankName / cardProgramNameKartın bankası ve programı (bilinmiyorsa null).
maskedCardNumberMaskeli kart numarası.
customer / itemsAPI 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

1234567891011121314151617181920212223242526

refund.completed Gövdesi

AdAçıklama
transactionIdİade edilen ödemenin işlem ID'si.
amountİade tutarı.
statusSUCCESSFUL veya PENDING.
merchantIdÜye işyeri ID'si.
orderIdÖdeme sayfası (checkout) ile alınan ödemelerde siparişin numarası.