Kripto Ödeme Geçidi API: Entegrasyondan Önce Kontrol Edilecek 12 Şey
Her kripto ödeme API'si fatura oluşturabilir. Farklar tekrar denemelerde, kısmi ödemelerde ve başarısız webhook'larda ortaya çıkar. Geliştiriciler için 12 maddelik kontrol listesi ve mistKET API'sinin her maddeye yanıtı.
Her kripto ödeme geçidi API'si aynı şeyi vaat eder: fatura oluştur, ödemeyi al, callback'i gönder. Farklar sonradan ortaya çıkar — iki istek yarıştığında, müşteri fatura tutarından biraz az gönderdiğinde, sunucunuz bir saat kapalı kaldığında ya da bir saldırgan yakaladığı bir isteği tekrar gönderdiğinde. API'yi dikkatle seçmek, hızlı entegre etmekten çok daha fazla zaman kazandırır.
Bu yazı, kod yazmadan önce kripto ödeme API'lerini karşılaştıran geliştiriciler ve CTO'lar için bir kontrol listesi. Her maddede neye bakmanız gerektiğini, neden önemli olduğunu ve mistKET API'sinin bunu nasıl ele aldığını göreceksiniz. Seçiminizi yaptıysanız ve adım adım kod istiyorsanız kripto ödeme API entegrasyonu rehberimize geçin.
Olması gereken asgari endpoint'ler
Kullanışlı bir kripto ödeme API'si “ödeme oluştur”dan fazlasını sunmalıdır. En azından şunlara bakın:
| Yetenek | Neden gerekli | mistKET endpoint'i |
|---|---|---|
| Fatura oluşturma | Her sipariş için süreli tek bir ödeme talebi | POST /invoices |
| Fatura sorgulama | Kaçırılan webhook'ta mutabakat | GET /invoices/{uuid} |
| Listeleme ve filtreleme | Yönetim ekranları ve gece mutabakatı | GET /invoices |
| Fatura iptali | Terk edilen siparişte stoğu serbest bırakmak | POST /invoices/{uuid}/cancel |
| Desteklenen varlıklar | Yalnızca şu an ödenebilen ağları göstermek | GET /assets |
| Kur teklifi | Fatura oluşturmadan kripto tutarını göstermek | GET /rate |
| Sağlık kontrolü | İzleme ve kontrollü geri dönüş | GET /health |
Bir sağlayıcı faturaları sorgulamanıza veya listelemenize izin vermiyorsa webhook'lara körü körüne güvenmek zorunda kalırsınız — ilk başarısız teslimatta kötü bir pozisyon.
1. Kimlik doğrulama: her istek imzalı mı?
Başlıkta gönderilen bir API anahtarı en zayıf seçenektir: onu yakalayan veya sızdıran herkes fatura oluşturup iptal edebilir. Her isteğin, ağ üzerinde hiç dolaşmayan bir gizli anahtarla imzalandığı bir API tercih edin. mistKET istekleri X-Api-Key, X-Api-Timestamp ve zaman damgası ile ham gövdenin HMAC-SHA256 imzasını taşır. Gizli anahtar işletme panelinde yalnızca bir kez gösterilir.
2. Tekrar (replay) koruması
İmza tek başına yakalanmış bir isteğin yeniden gönderilmesini engellemez. Zaman damgası penceresi ve nonce desteği arayın. mistKET sunucu saatinden ±300 saniyeden fazla sapan zaman damgalarını reddeder ve durum değiştiren isteklerde aynı imzayı iki kez kabul etmez. İmza sürüm 2, her isteğe bir nonce ekler ve metot ile yolu da imzalar; böylece bir imza başka bir endpoint'te yeniden kullanılamaz.
3. Fatura oluşturmada idempotency
Ağlar zaman aşımına uğrar. Ödeme akışınız “fatura oluştur” çağrısını tekrar denerse bir sipariş için iki fatura oluşmamalıdır. İyi bir API idempotency anahtarı sunar. mistKET'te bu görevi kendi order_id değeriniz üstlenir: aynı sipariş numarasıyla tekrar çağırdığınızda yenisi oluşturulmaz, mevcut fatura "idempotent": true ile döner.
4. Gerçek ödemeleri kapsayan bir durum modeli
“Ödendi / ödenmedi” yetmez. Müşteriler borsa komisyon kestiği için biraz eksik, bazen fazla gönderir ya da süre dolduktan sonra öder. API'nin bu durumları açıkça gösterdiğinden emin olun. mistKET faturaları new, pending, underpaid, paid, confirmed, overpaid, expired ve cancelled durumlarından geçer; paid_amount, remaining_amount, can_pay_remaining ve under_review gibi alanlar sayesinde kodunuz hiçbir zaman tahmin yürütmek zorunda kalmaz.
paid, transferin tespit edildiği ve onay beklediği anlamına gelir; siparişi yalnızca confirmed veya overpaid durumunda teslim edin.5. Görünür onaylar
API, ödemenin kaç blok onayı aldığını ve kaç onay gerektiğini, ayrıca işlem hash'ini ve explorer linkini söylemelidir. Böylece ödeme destek talepleri hızlı bir kontrole dönüşür. mistKET her fatura için confirmations, required_confirmations ve hash, tutar, durum ve explorer URL'si içeren bir transactions[] dizisi döndürür.
6. Kur sabitleme ve fiyat para birimleri
Siz fiat ile fiyatlarsınız, müşteri kripto ile öder. Hangi fiat para birimlerinin kabul edildiğini ve kurun ne kadar süre sabit kaldığını sorun. mistKET USD, EUR, TRY, RUB, GBP ve AED (veya doğrudan kripto sembolü) cinsinden fiyat kabul eder, kuru fatura ömrü boyunca sabitler ve bu süreyi fatura başına 5 ile 1.440 dakika arasında ayarlamanıza izin verir.
7. Ağ seçimi
Ağı API çağrısında sabitleyebiliyor musunuz, yoksa müşterinin ödeme sayfasında seçmesine mi bırakıyorsunuz? İkisi de işe yarar: sabitlemek botlara ve otomatik akışlara uyar, müşteriye bırakmak yanlış ağdan gönderimleri azaltır. mistKET ikisini de pay_currency + network veya asset_id ile destekler; GET /assets bir ağda boş adres yoksa available: false döndürür. Bugün TRON (TRC-20) üzerinde USDT etkindir; ek varlık ve ağlar talep üzerine işletme bazında açılır. TRON'un neden yaygın varsayılan olduğunu USDT TRC20 ve ERC20 yazımızda bulabilirsiniz.
8. İmzalı, tekrar denenen ve izlenebilir webhook'lar
Entegrasyonların çoğu webhook'larda bozulur. Dört şeyi kontrol edin: gövde imzalı mı, eski teslimatları reddetmek için zaman damgası var mı, başarısız teslimatlar saniyeler değil saatler boyunca tekrar deneniyor mu ve her teslimatın tekilleştirme için bir kimliği var mı. mistKET webhook'ları ayrı bir webhook anahtarıyla imzalar, X-Mistket-Delivery ve X-Mistket-Event başlıklarını gönderir ve 2xx olmayan yanıtları 10 sn, 30 sn, 2 dk, 10 dk, 30 dk, 1 sa, 2 sa ve 3 sa aralıklarla yeniden dener; teslimat geçmişi panelde görünür. Handler tasarımının ayrıntıları kripto ödeme webhook'ları yazımızda.
9. Belgelenmiş hatalar ve hız limitleri
Hatalı imza, engellenen IP veya doğrulama hatasının neye benzediğini önceden bilmelisiniz. mistKET tutarlı bir { "success": false, "error": … } gövdesi döndürür, doğrulama hatalarında alan bazında ayrıntı verir, standart kodlar (401, 403, 404, 422, 429, 503) kullanır ve limitini belgeler: API anahtarı başına dakikada 120 istek.
10. Ağ düzeyinde kontroller
IP izin listesi sayesinde sızan bir anahtar sizin sunucularınız dışında hiçbir yerden kullanılamaz. mistKET bunu panelden tanımlamanıza izin verir; başka adreslerden gelen istekler 403 alır. İmzalı istekler ve kısa zaman penceresiyle birlikte en yaygın saldırı yollarını kapatır.
11. SDK bağımlılığı yok
SDK'lar, dil sürümünüzün gerisinde kalana kadar pratiktir. Düz HTTPS ve JSON üzerine kurulu, imzalamanın tek bir HMAC çağrısı olduğu bir API PHP, Node.js, Python, Go veya bir shell betiğinden çalışır. mistKET API dokümantasyonunda PHP, Node.js ve Python için kopyala-yapıştır istemciler yayınlar, ancak hiçbiri zorunlu değildir.
12. Geliştirici olmayanlar için manuel yol
API öncelikli işletmelerin de zaman zaman tek seferlik bir müşteriye fatura kesmesi gerekir. Faturaların bir panelde de oluşturulup link olarak paylaşılabildiğinden emin olun; satış ve destek ekipleri geliştiricilere ihtiyaç duymasın. mistKET'te aynı faturalar işletme panelinde de bulunur ve her barındırılan ödeme sayfası bir ödeme linki olarak çalışır.
GET /invoices/{uuid} çağırıp karşılaştırın. İmzalamanızı, webhook handler'ınızı ve mutabakatınızı tek seferde doğrularsınız.Kripto ödeme API'si değerlendirirken alarm işaretleri
- İmzasız webhook'lar ya da yalnızca gizli bir URL ile “korunan” webhook'lar.
- Oluşturulduktan sonra faturayı sorgulama imkânı olmaması.
- Eksik veya fazla ödeme durumu olmaması — uç durumlar destek sohbetine düşer.
- Yalnızca birkaç dakika süren tekrar denemeler veya teslimat kaydının olmaması.
- Belgelenmemiş hız limitleri ve hata formatları.
- İşlem başına belirsiz fiyatlandırma — kripto ödeme geçidi komisyonları rehberimizle karşılaştırın.
mistKET API erişimi nasıl alınır?
İşletmeler mistKET ekibi tarafından kabul edilir: web sitenizi, iş türünüzü ve beklenen hacminizi Telegram'da @mistnetwork adresine yazın. Onaylandıktan sonra API anahtarınızı, gizli anahtarınızı ve webhook ayarlarınızı işletme panelinde oluşturursunuz. Tipik bir entegrasyon bir öğleden sonra sürer.
Başlamadan önce geliştirici bölümünü, fiyatlandırmayı ve eksiksiz API referansını inceleyin.
