Webhook İmza Doğrulayıcı
İşletme panelinden yapılandırdığınız webhook teslimlerinin X-Kaptan-Signature-256 başlığını doğrular: signingPayload = timestamp + "." + rawBody, imza HMAC-SHA256(secret, signingPayload). timestamp, X-Kaptan-Timestamp başlığındaki epoch milisaniye değeridir.
Buradaki secret, işletme panelindeki Entegrasyon → Webhook ekranından alınan webhook imza sırrıdır — Partner API isteklerini imzaladığınız API secret'ı DEĞİLDİR.
Gövdeyi ham hâliyle yapıştırın — JSON'u parse edip yeniden serileştirmek imzayı bozar.
Hesaplama tamamen tarayıcıda (WebCrypto) yapılır.
Secret ve timestamp girildiğinde beklenen imza hesaplanır.
Teslim Başlıkları
| Başlık | Değer |
|---|---|
X-Kaptan-Signature-256 | t=<timestamp>,v1=<hex> — doğrulamanız gereken imza. |
X-Kaptan-Signature | sha256=<hex> — aynı imzanın eski biçimi (geriye uyumluluk için). |
X-Kaptan-Timestamp | İmzaya giren zaman damgası, epoch milisaniye. |
X-Kaptan-Event | Olay adı (ör. PAYMENT_SUCCEEDED). |
X-Kaptan-Webhook-Id | Teslim kaydının kimliği; tekrar denemelerde aynı kalır, mükerrer işlemeyi önlemek için kullanın. |
X-Kaptan-Resource | PosTransaction:<transactionRef> biçiminde kaynak. |
X-Kaptan-Secret-Version | İmzada kullanılan sır sürümü — sır yenilemesinde hangi sırla doğrulayacağınızı gösterir. |
X-Correlation-Id | Destek talepleri için korelasyon kimliği. |
User-Agent | Kaptan-Webhook/1.0 |
Gövde, anahtarları alfabetik sıralı kompakt JSON'dur; imza bu ham metin üzerinden hesaplanır. 2xx dışındaki yanıtlar teslimi başarısız sayar ve olay tekrar denenir.
Olaylar ve Gövde
| Olay | Ne zaman |
|---|---|
PAYMENT_SUCCEEDED | Tahsilat gerçekleşti (provizyonda kapatma anında). |
PAYMENT_AUTHORIZED | Provizyon açıldı, tutar bloke — tahsilat değildir. |
PAYMENT_FAILED | Ödeme başarısız. |
PAYMENT_REFUNDED | İade yapıldı. |
PAYMENT_VOIDED | İşlem iptal edildi. |
PAYMENT_REVERSED | İşlem otomatik geri alındı. |
PAYMENT_SETTLED | Hakediş tamamlandı. |
CHARGEBACK_RECEIVED / CHARGEBACK_WON / CHARGEBACK_LOST | Ters ibraz süreci. |
MERCHANT_APPROVED / MERCHANT_REJECTED | İşletme başvurusu sonucu. |
TEST | Panelden gönderilen deneme olayı. |
| Alan | Anlamı |
|---|---|
eventType | Olay adı. |
transactionRef | İşlem referansı — Partner API uçlarındaki değerle aynı. |
orderNumber | Ödemede gönderdiğiniz sipariş numarası. |
amount / currency | İşlem tutarı ve para birimi. |
paymentMethod / installment / threed | Ödeme yöntemi, taksit sayısı ve 3D Secure bilgisi. |
status / success | İşlem durumu; success tahsilat gerçekleşmişse true. |
merchantId | İşletme kimliği. |
Tahsilat kaydı üzerinden yayınlanan olaylarda gövde status, success, merchantId, installment, threed yerine checkoutId, referenceCode, capturedDate, refundedDate alanlarını taşıyabilir. Aynı işlem için aynı olay yalnız bir kez kuyruğa alınır.