Webhook URL
Genel bakış
Bu özellik, ödenen faturanın verilerini satıcının sunucusuna iletir. Amacı, satıcının mağazasının ödemeyi otomatik olarak işleyebilmesi ve ürünü veya hizmeti alıcınıza teslim edebilmesidir.
Webhook URL, her proje için ayrı ayrı ayarlanır ve satıcının mağazasındaki ödeme işleyici betiklerine işaret eder. Adres HTTPS ve bir alan adı kullanmalıdır: IP adresleri kabul edilmez ve sertifika her teslimatta doğrulanır.
Bir faturanın durumu her Ödendi (Paid) olduğunda hizmet, bu adrese aşağıdaki biçimde bir POST isteği gönderir:
{
"wallet":{
"id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
"name":"usdt-tron",
"blockchain":"tron",
"cryptocurrency":"usdt",
"address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
},
"project":{
"id":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
"name":"My project",
"commissionPayer":"seller",
"commissionRate":1
},
"invoice":{
"id":"a4c9e2ee-9a03-43e5-a1a1-00caf679d16a",
"uid":"AFhygKX21ecd",
"createDatetime":"2024-02-26 13:29:24",
"timeToPayDatetime":"2024-02-27 01:29:24",
"commissionFiatUSD":0.05,
"amountFiatUSD":5.02,
"amountFiat":5,
"calcAmountFiat":5.02,
"currencyFiat":"USD",
"description":null,
"serviceData":null,
"status":"paid"
},
"payment":{
"id":"f986ad8d-2298-473d-982a-efbc817b975d",
"amount":5.02,
"hash":"74763b65e43bcc9492a6ce9a7f26fbfdbd7635aecd3454420b5e9534cba50ee6",
"transactionDatetime":"2024-02-26 13:32:57"
}
}
Bildirim, Ödendi durumuna her geçişte gönderilir — hem hizmet ödemeyi otomatik olarak bulduğunda hem de satıcı ödemeyi faturayla manuel olarak eşleştirdiğinde.
İstek parametreleri
| Parametre | Açıklama |
|---|---|
wallet.id | UUID biçiminde cüzdan ID'si |
wallet.name | Cüzdan adı |
wallet.blockchain | Kripto cüzdanının blockchain'i |
wallet.cryptocurrency | Cüzdanın kripto parası |
wallet.address | Kripto cüzdanının adresi |
project.id | UUID biçiminde proje ID'si |
project.name | Proje adı |
project.commissionPayer | Hizmet ücretini kimin ödediği |
project.commissionRate | % cinsinden ücret oranı |
invoice.id | UUID biçiminde fatura ID'si |
invoice.uid | Fatura ID'si (alıcı için) |
invoice.createDatetime | Faturanın oluşturulma tarihi ve saati (UTC) |
invoice.timeToPayDatetime | Faturanın alıcı için geçerli olduğu son tarih ve saat (UTC). Ödeme araması, bu işaretten sonra 1 saat daha devam eder — bu, yavaş ağlar içindir. Bu yüzden, zaten süresi dolmuş olarak gösterilen bir fatura için bildirim gelebilir |
invoice.commissionFiatUSD | Hizmet ücreti tutarı. invoice.amountFiatUSD tutarından hesaplanır |
invoice.amountFiatUSD | USD cinsinden tutar. Fatura oluşturulurken invoice.amountFiat değerinden güncel kura göre hesaplanır. Ödeme anında üzerine fiilen alınan tutar yazılır, o andaki kurla USD'ye dönüştürülerek. invoice.commissionFiatUSD içindeki ücret de bundan yeniden hesaplanır |
invoice.amountFiat | Faturanın itibari para cinsinden orijinal tutarı. Değişmez |
invoice.calcAmountFiat | Ödeme anındaki kripto kuruna göre invoice.currencyFiat para biriminde hesaplanan tutar. Alıcı, faturayı hemen değil oluşturulmasından bir süre sonra ödemiş olabileceği için invoice.amountFiat değerinden farklı olabilir. Bu süre içinde kripto kuru, invoice.currencyFiat karşısında iki yönde de hareket etmiş olabilir |
invoice.currencyFiat | İtibari para birimi |
invoice.description | Fatura oluşturulurken ayarlanan açıklama |
invoice.serviceData | Fatura oluşturulurken ayarlanan hizmet verisi |
invoice.status | Fatura durumu |
payment.id | UUID biçiminde ödeme ID'si |
payment.amount | Kripto para cinsinden ödeme tutarı |
payment.hash | On-chain işlemin hash'i |
payment.transactionDatetime | On-chain işlemin tarihi ve saati (UTC) |
Bildirim imzası
Her istek, webhook gizli anahtarıyla imzalanır. İmza, X-Timestamp ve X-Signature başlıklarında taşınır ve bildirimin, işleyicinizin adresini öğrenen bir yabancıdan değil hizmetten geldiğinden emin olmanızı sağlar.
Siparişi işlemeden önce imzayı doğrulayın. Mekanizma ve hazır örnekler Webhook imzası doğrulama sayfasındadır.
İşleme önerileri
Bir bildirimi ödeme süresi geçti diye reddetmeyin. “Faturanın süresi dolmuş, o hâlde ödeme geçersiz” gibi bir kontrol mantıklı görünür ama gerçek ödemelerin bir bölümünü keser: yavaş ağlarda işlem, süre geçtikten sonra onaylanabilir ve satıcı, süresi dolmuş bir faturaya ödemeyi manuel olarak eşleştirebilir. Bildirimin kendisi ödemeyi onaylar.
Tutarı orijinal alan invoice.amountFiat üzerinden doğrulayın. Bu, faturanın kesildiği tutardır ve değişmez. amountFiatUSD alanı, fiilen alınan tutarı yansıtır ve kesilen tutardan farklı olabilir — hem kur hareketi hem de manuel ödeme eşleştirme nedeniyle.
Tutarları sayı olarak ayrıştırın. Sondaki sıfırlar atılır: 10.00 tutarı 10 olarak gelir; görüntüleme için kendi tarafınızda biçimlendirin. 0.0001 altındaki tutarlar üstel gösterimle gelir, örneğin 1.0e-6 — standart JSON ayrıştırma doğru sayıyı döndürür; yalnızca elle dize ayrıştırma bozulur.
Bildirimleri idempotent şekilde işleyin. Aynı bildirim yeniden gelebilir — örneğin betiğiniz ödemeyi başarıyla işlediği hâlde 2xx dışı bir kod döndürdüyse. Siparişi teslim etmeden önce, bu invoice.id değerinin daha önce işlenip işlenmediğini kontrol edin.
Çıktıda değerlere kaçış uygulayın. invoice.description ve invoice.serviceData alanları, tam olarak satıcının gönderdiği hâliyle geri gelir. Bunları HTML'de görüntülüyorsanız kendi tarafınızda kaçış uygulayın.
Teslimat takvimi
Webhook URL'deki sunucu, 2xx HTTP koduyla yanıt vermelidir. Başka bir kod, zaman aşımı veya kopan bağlantı başarısız teslimat sayılır.
Yönlendirmeler izlenmez: 301 veya 302 yanıtı, yeni adrese geçiş değil başarısız teslimattır. İşleyicinin nihai adresini ayarlayın.
Bağlantıya 5 saniye, isteğin tamamına 10 saniye tanınır. İşleyici bu süreye sığmazsa teslimat başarısız sayılır.
Başarısız teslimattan sonra hizmet, şu takvimle yeniden dener:
- Son başarısız teslimattan 5 dakika sonra
- 15 dakika sonra
- 30 dakika sonra
- 1 saat sonra
- 3 saat sonra
- 6 saat sonra
- 12 saat sonra
- 24 saat sonra
Bundan sonra teslimat denemeleri durur.
Webhook URL'yi devre dışı bırakma
Bazen mağazanın webhook betiği ödemeyi doğru işler ama 2xx dışı bir HTTP kodu döndürür. Bu, sunucumuzun yukarıdaki takvimle sık sık yeniden denemesine yol açar ve hem bizim sunucumuza hem sizinkine ek yük bindirir.
Bu tür durumları önlemek için projede Webhook URL'yi devre dışı bırakan bir mekanizmamız vardır. Bununla karşılaşmamak için şu adımları izleyin:
- Webhook işleyici kodunuzu, ödeme başarıyla işlendiğinde 2xx kodu, genellikle 200, döndürecek şekilde değiştirin. Herhangi bir emülatörle, örneğin Postman'le test edin.
- Ayarların düzeltilmesi için teknik desteğe başvurun.
- Proje ayarlarında Webhook URL'yi yeniden etkinleştirin ve projeyi kaydedin.