Bir kripto ödeme API'sini entegre etmek, sağlayıcıdan bağımsız olarak öngörülebilir bir biçim izler: bir fatura oluşturursunuz, bir ödeme ekranını yönlendirir veya gömer, ödeme ilerledikçe asenkron webhook'lar alır, onları doğrular ve kendi kayıtlarınızla mutabık kalırsınız. Zor kısım mutlu yol değil — kenarlardır.
Çekirdek akış
Çoğu ağ geçidi aynı yaşam döngüsüne sahip bir REST API sunar. Bunu sunucu tarafında çağırırsınız (bir API anahtarını tarayıcıda asla açığa çıkarmayın) ve bir siparişin ödenip ödenmediğinin doğruluk kaynağı olarak tarayıcı yönlendirmesini değil webhook'u ele alırsınız.
Sipariş durum makinenizi önce tasarlayın: beklemede → eksik ödendi/ödendi → onaylandı → tamamlandı, süresi doldu ve fazla ödendi için açık dallarla. Bunu önden bağlamak, çift teslimata neden olan karışık koşulları önler.
- Tutar, para birimi, sipariş kimliği ve bir webhook URL'si ile bir fatura oluşturun.
- Barındırılan ödeme ekranını gösterin veya adresi ve tutarı kendiniz çizin.
- Her durum değişikliği için webhook'lar alın ve imzalarını doğrulayın.
- Ödemenin gerekli onaylara ulaştığını teyit etmeden yerine getirmeyin.
- Webhook'u zincir üzerindeki işlemle ve siparişinizle mutabık kılın.
Bir fatura oluşturma
Bir fatura, belirli bir tutarı sınırlı bir süre için belirli bir siparişe bağlar. Webhook'un tahmin olmadan geri eşleştirebilmesi için sipariş kimliğinizi meta veri olarak gönderin ve ağ geçidinin döndürdüğü fatura kimliğini saklayın.
Teklifler süresi dolar — ağ geçidi bir oranı birkaç dakika kilitler. Faturanın son kullanma ve durumunu saklayın, böylece kullanıcı arayüzünüz bir geri sayım gösterebilir ve geç bir ödeme kayıp bir sipariş değil bir mutabakat durumu olarak ele alınır.
Webhook'lar doğruluğun kaynağıdır
Ödemeden sonraki tarayıcı yönlendirmesi bir kolaylıktır, bir garanti değil — kullanıcı sekmeyi kapatabilir. Sunucunuzun aldığı webhook, üzerine hareket ettiğiniz şeydir. Her webhook'u doğrulayın: tek bir alana bile güvenmeden önce imzayı (genellikle gizli anahtarınızla ham gövde üzerinde bir HMAC) kontrol edin.
Webhook işlemeyi idempotent yapın. Ağ geçitleri teslimatları yeniden dener, bu yüzden aynı 'ödendi' olayı iki kez gelebilir; işlemenizi olay veya fatura kimliğine anahtarlayın ve tekrarlanan teslimatları bir işlemsiz hale getirin. Hızlıca bir 2xx döndürün ve yavaş işi asenkron yapın, böylece ağ geçidi zaman aşımına uğrayıp gereksiz yere yeniden denemez.
Onaylar ve kesinlik
Bir ödeme, kesinleşmeden çok önce (bellek havuzunda veya sıfır onayla) görülebilir. Tutara ve zincire uygun bir onay eşiği belirleyin ve yalnızca karşılandığında yerine getirin. Hızlı zincirlerdeki küçük stabilcoin ödemeleri için bu hızlıdır; büyük tutarlar için daha fazla bekleyin.
Kendi ilk görüşünüz yerine ağ geçidinin 'onaylandı' durumuna güvenerek ve riski kabul etmediğiniz sürece sıfır onaylı bir ödemede mal bırakmayarak yeniden düzenlemelere ve çift harcamalara karşı korunun.
Mutabakat ve hata durumları
Mutabakat, her 'ödendi' siparişinin gerçek bir zincir üzerindeki işleme eşlendiğini ve tersini kanıtlamanın günlük işidir. Her siparişte işlem hash'ini, alınan tutarı ve ağı saklayın, böylece bir tutarsızlık bir soruşturma değil bir sorgu olur.
Eksik ödemeleri (alıcı çok az gönderdi), fazla ödemeleri (farkı iade edin veya alacak yazın), yanlış ağ göndermelerini ve süresi dolup sonra ödenen faturaları açıkça planlayın. Bunlar hacimde nadir uç durumlar değil — haftalık olaylardır ve onları sessizce ele alan bir sistem, 'üretime hazır'ın gerçek anlamıdır.
Sıkça sorulan sorular
Tarayıcı yönlendirmesine mi yoksa webhook'a mı güvenmeliyim?
Webhook'a. Yönlendirme, kullanıcı sekmeyi kapatırsa kaybolabilir ve taklit edilebilir. Webhook'un imzasını sunucu tarafında doğrulayın ve bir siparişin ödendiğine dair yetkili sinyal olarak ele alın.
Bir webhook'un iki kez işlenmesini nasıl durdururum?
İşlemeyi idempotent yapın. Ağ geçitleri teslimatları yeniden dener, bu yüzden mantığınızı fatura veya olay kimliğine anahtarlayın ve bir tekrarı işlemsiz yapın. Aynı 'ödendi' olayı tekrar geldi diye bir siparişi asla iki kez yerine getirmeyin.
Kaç onay beklemeliyim?
Tutara ve zincire bağlıdır. Hızlı ağlardaki küçük stabilcoin ödemeleri neredeyse anında kesin sayılabilir; daha büyük tutarlar daha fazla onayı haklı çıkarır. Kendi ilk görüşünüz yerine ağ geçidinin 'onaylandı' durumunu kullanın.
Bir müşteri eksik veya fazla öderse ne olur?
İkisini de açıkça ele alın. Ağ geçitleri eksik ödemeleri işaretler, böylece farkı isteyebilir veya iade edebilirsiniz; fazla ödemeler için fazlalığı iade eder veya alacak yazarsınız. Bu dalları önden kurmak, bir demo ile üretim arasındaki farktır.