Geçerli bir ödeme bildirimi aynı siparişin iki kez teslim edilmesine yol açmamalıdır. Kripto ödeme webhook'ları için iki ayrı koruma gerekir: önce olayı kimin gönderdiğini doğrulamak, ardından tekrar işlendiğinde ticari işlemin güvenle aynı sonucu vermesini sağlamak. İmza ilk soruyu yanıtlar. İdempotans ikinciyi yanıtlar.
Bu kılavuz, tek seferlik dijital ürün satışlarını, lisansları veya hesap bakiyesi yüklemelerini Yolfi'ye bağlayan geliştiriciler içindir. Yolfi'nin kendi webhook biçimini ve önerilen bir uygulama tasarımını açıklar; hazır bir sipariş teslim hizmeti sunmaz. Aboneliklerde erişim, aboneliğin yaşam döngüsüne de bağlıdır; tek seferlik sipariş kuralını her yenilemede kullanmayın.
Gerçek bir webhook neden yine de tekrarlı işleme yol açabilir?
Alıcı olayı başarıyla kaydetmiş olsa bile HTTP yanıtı kaybolabilir. Gönderici bu durumda yeniden dener. Arka plan işleyiciniz de erişim verdikten sonra, tamamlandığını kaydetmeden önce çökebilir. Bu durumların hiçbiri müşterinin ikinci bir ödeme yaptığı anlamına gelmez.
Yolfi'nin webhook olay referansı, en az bir kez teslimi ve birden fazla uç nokta için bağımsız yeniden denemeleri belgeler. Aynı olayın, ilk teslim hâlâ işlenirken bile yeniden gelebileceğini hesaba katın. Belirli bir yeniden deneme takvimine güvenmeyin ve bildirimlerin uygulamanıza her zaman oluşturulma sırasıyla ulaşacağını varsaymayın.
Üç ayrı kimliği birbirinden ayırın:
| Kimlik | Neyi tanımlar? | Önerilen kontrol |
|---|---|---|
İmzalı olay id değeri |
Tekrarlanan teslimler dahil tek bir sağlayıcı olayını | Sağlayıcı, kuruluş ve ortam kapsamında benzersiz olay kaydı |
| Fatura veya ödeme referansı | Tek bir ödeme girişimini | İlgili ticari siparişle saklanan ilişki |
| Ticari sipariş referansı | Müşterinin ne alması gerektiğini | O sipariş için benzersiz teslim işlemi |
Yalnızca yinelenen olayları ayıklamak yeterli değildir: bir sipariş için başarılı olan iki ödeme girişimi farklı olay kimlikleri taşıyabilir. Sipariş düzeyindeki koruma, ek tahsilat ayrıca incelenirken ikinci bir lisans veya hesap kredisi verilmesini önler.
Alanlarına güvenmeden önce ham isteği doğrulayın
Güncel Yolfi imza talimatlarını izleyin. Yerel biçimdeki istekler X-Yolfi-Signature kullanır: bu değer, ilgili uç noktanın imzalama sırrıyla ham istek gövdesi üzerinden hesaplanan ve Base64 ile kodlanan HMAC-SHA256 imzasıdır. Kuruluşun API anahtarı, webhook sırrı değildir.
JSON ara yazılımı değiştirmeden önce özgün gövdeyi alın. İmzayı hesaplayıp sabit zamanlı bir karşılaştırma işleviyle karşılaştırın; eksik veya hatalı biçimlendirilmiş imzaları hiçbir ticari işlem yapmadan reddedin. İmzalama sırlarını kaynak dosyalarında veya destek günlüklerinde değil, bir sır yöneticisinde ya da korumalı ortam yapılandırmasında tutun.
İstek verisini ancak doğrulamadan sonra ayrıştırıp denetleyin. Tekrarları ayıklamak için imzalı gövdedeki id değerini kullanın. X-Yolfi-Event-ID, kolaylık sağlayan bir kopyadır; ayrıca imzalanmış bir değer değildir. Kullanıyorsanız gövdedeki olay kimliğine eşit olmasını zorunlu kılın. Alıcı uç noktayı beklenen kuruluşa bağlayın ve varsa orgId alanını doğrulayın. Kullanıcının sağladığı ek bilgiler, hangi kuruluşun verilerine erişim yetkisi olduğunu belirlememelidir.
Geçerli bir imza eski bir teslimi yeni yapmaz. İşlenen olay kimliklerini saklamak hâlâ gereklidir. Yolfi'nin belgelenmiş imzası zaman damgasına dayalı bir güncellik kontrolü değildir; bu nedenle yalnızca HMAC doğrulamasının yeniden oynatmayı engellediğini ileri sürmeyin.
Önce kaydedin, sonra alındıyı onaylayın ve asenkron işleyin
Kalıcı bir gelen olay kutusu kullanın: kimliği doğrulanmış olayı ve işleme durumunu kaydeden bir uygulama tablosu. Olayı, ayrı bir “var mı?” kontrolünün ardından korumasız ekleme yaparak değil, veritabanındaki benzersizlik kısıtı altında ekleyin. Eşzamanlı isteklerin ikisi de ayrı kontrolden geçebilir.
Kalıcı kabulden sonra, kimliği doğrulanmış bir tekrar zaten kayıtlı olsa bile, hızla 200 OK döndürün. Kalıcı kayıt başarısız olursa olayı kabul edilmiş olarak onaylamayın. Hızlı yanıtın ardından yalnızca bellekte çalışan bir görev kalıcılık sağlamaz: yeniden başlatma, uygulamanızın tuttuğu tek kopyayı kaybettirebilir.
Arka plan işleyicisi daha sonra kaydedilen olayı yükleyebilir, siparişle ilişkisini doğrulayabilir ve iş durumunu değiştirebilir. Başarısız işleri yeniden deneme sayısı, sonraki adım ve uyarılardan sorumlu kişiyle görünür tutun. Kısıtlı erişimli depolamada yalnızca gerekli olay verilerini saklayın; olay gövdeleri müşteri bilgileri içerebilir.
Teslimi ödeme onayına ve doğru siparişe bağlayın
Yolfi webhook kılavuzu, payment.confirmed olayını sipariş teslimini başlatan temel olay olarak tanımlar. invoice.created, müşterinin ödeme yaptığını değil, fatura oluşturulduğunu gösterir. Tarayıcı yönlendirmesi veya ekran görüntüsü, sunucuda doğrulanmış ödeme onayının yerini tutmaz.
Olayı sunucuda saklanan bir siparişle eşleştirin. Yerel akışta bağımsız API Checkout olayları checkoutSessionId ve merchantOrderId içerebilir; paylinkId ise bulunmayabilir. Sırf Paylink kimliği yok diye geçerli bir bağımsız satın almayı reddetmeyin. Aynı şekilde, yeniden kullanılabilir bir Paylink kimliği de tek başına alıcının siparişini benzersiz biçimde tanımlamaz.
Teslimden önce beklenen kuruluşu, ortamı, ödeme girişimini ve ticari tutarın bağlamını kontrol edin. Belgelenen amount, satıcının ödeme token'ında alacağı nihai tutardır; kendiliğinden yerel para birimindeki özgün fatura toplamınız değildir. Bu iki sayıyı aynı birimdeymiş gibi karşılaştırmayın. Sunucunun onayladığı özgün siparişi ve fiyatlandırma bağlamını saklayın.
Dinamik satın almalarda sipariş ile oturum arasındaki ilişkiyi korumak için API Checkout akışını kullanın. Sabit ürünlerde ödeme linkleri, yeniden kullanılabilir bir ödeme giriş noktası sağlar; teslim kararının sorumluluğu yine uygulamanızdadır.
Yalnızca olay tablosunu değil, işlemin etkisini de koruyun
Tamamen kendi veritabanınızda yerine getirilen bir sipariş için olay sonucunu ve siparişin durum değişikliğini tek bir veritabanı işlemi içinde kaydedin. Tek seferlik sipariş başına yalnızca bir erişim hakkı verme gibi benzersiz bir ticari işlem kuralı uygulayın. Yinelenen olay yeni bir hak vermek yerine mevcut sonucu döndürmelidir.
Teslim için başka bir hizmete çağrı yapılıyorsa kalıcı bir giden işlem kutusu kullanın: amaçlanan işlemi siparişin durum değişikliğiyle birlikte kaydedin, ardından bir arka plan işleyicisi bunu iletsin. Alıcı destekliyorsa sonraki işleme siparişe dayalı sabit bir idempotans anahtarı verin. İşleyici uzaktaki işlem başarıyla tamamlandıktan sonra çökerse, giden işlem kutusu tek başına uzaktaki tekrarları önlemez.
Hedef sistem idempotansı veya sonuç sorgulamayı desteklemiyorsa geri alınamaz bir işlemi körlemesine yeniden denemek yerine belirsiz sonucu mutabakat için bekletin. Bir HTTP webhook'u, her veritabanı, kuyruk ve dış hizmet genelinde “tam olarak bir kez” işlem garantisi veremez.
Eski olayların tamamlanmış siparişi önceki duruma döndürmesini engelleyin. invoice.overdue olayı tek bir ödeme girişimiyle ilgilidir ve yerine getirilmiş siparişin sonucunu silmemelidir. Yinelenen erişimde sağlayıcı, fatura olaylarını subscription.overdue ve subscription.cancelled olaylarından ayırır; belgelenmiş abonelik politikasını ayrıca uygulayın.
Gerçek siparişleri kabul etmeden önce hata yollarını test edin
Alıcı ve arka plan işleyicisi için şu kabul senaryolarını kullanın:
- Aynı imzalı olayı iki kez ve eşzamanlı iletin: tek kayıtlı olay, tek ticari etki oluşmalı.
- İşleyiciyi siparişin durum değişikliğinden önce ve sonra durdurun: kurtarma ikinci kez erişim vermemeli.
- Bir sipariş için iki onaylanmış ödeme girişimi iletin: sipariş bir kez teslim edilmeli, ek tahsilat işaretlenmeli.
- Geçersiz imza, eşleşmeyen kuruluş ve bilinmeyen sipariş gönderin: teslim yapılmamalı.
- Onaydan sonra eski bir fatura olayı iletin: tamamlanmış teslim geri alınmamalı.
- Canlı ortam alıcısına test olayı gönderin: gerçek lisans, sevkiyat veya hesap kredisi oluşmamalı.
Yolfi yönetim panelinin test olayları livemode: false ve evt_test_ ile başlayan bir kimlik kullanır. Teslimi ve olay verisinin işlenmesini sınarlar, ancak gerçek ödeme kayıtları oluşturmazlar. Test ve canlı ortam etkilerini açıkça ayırın; başarılı bir test bildirimi, satın alma bedelinin tahsil edildiğinin kanıtı değildir.
İşlenmeyi bekleyen doğrulanmış olayları, işleyici hatalarını ve teslim sonucu olmayan onaylı ödemeleri izleyin. Bu istisnaları ödeme mutabakatı kontrol listesine bağlayın. İkinci tahsilat bir yeniden deneme değil de gerçekten ek bir ödemeyse kanıtları silmek yerine iade inceleme prosedürünü izleyin.
Sık sorulan sorular
İmza doğrulaması hesaba iki kez kredi eklenmesini önler mi?
Hayır. Kaynağın gerçekliğini ve veri bütünlüğünü doğrular. Gerçek bir olay birden fazla kez gelebilir; daha önce geçerli olan bir istek yeniden oynatılabilir. Olay kimliklerini kalıcı kaydedin ve sipariş düzeyinde bir ticari kısıt uygulayın.
Olayı kaydetmeden önce başarılı yanıt vermeli miyim?
Hayır. Kalıcı kabulden sonra alındıyı onaylayın, ardından daha yavaş işleri asenkron yürütün. Aksi hâlde yanıttan sonraki bir çökme, olayı fark edilmeden kaybettirebilir.
İşlem özeti tekrarları ayıklamak için yeterli bir anahtar mı?
Webhook işleme için yeterli değildir. Olay teslimlerinde belgelenmiş imzalı olay kimliğini, sipariş tesliminde ise kendi sipariş anahtarınızı kullanın. Transferlerle siparişlerin kimlikleri farklıdır; tek bir blokzincir işlemi birden fazla transfer içerebilir.
Adaptör verileri için aynı işleyiciyi kullanabilir miyim?
Veri sözleşmelerini kontrol etmeden kullanmayın. Bu makale, NONE adaptörüyle kullanılan yerel biçimi açıklar. Sağlayıcılarla uyumlu adaptörler farklı bir veri yapısı kullanabilir; yerel ayrıştırma ve ilişkilendirme kurallarını yeniden kullanmadan önce belgelenmiş alanlarını doğrulayın.
Sonuç: doğrulayın, kaydedin ve bir kez teslim edin
Güvenilir kripto ödeme otomasyonu, kimliği doğrulanmış teslimi siparişin ticari etkisinden ayırır. Ham gövdenin imzasını doğrulayın, olayı kalıcı kaydedin, siparişi eşleştirin ve yeniden denemelerde teslimi güvenli kılın. Sabit ürünler için Yolfi ödeme linkleriyle, dinamik siparişler için ise belgelenmiş sunucu tarafından oluşturulan oturumla başlayın; her satın almayı yalnızca bir kez teslim etme sorumluluğunu uygulamada tutun.
