Giriş/Genel bilgiler

Genel Bilgiler

2328.io ile kripto para ödeme işleme ve çekim entegrasyonu için teknik şartname.

2328.io API dokümantasyonuna hoş geldiniz. Bu referans, kripto para ödeme işleme ve çekimleri uygulamanıza nasıl entegre edeceğinizi anlatır.

Başlarken

Entegrasyona başlamak için:

2328.io üzerinde bir merchant hesabı ve proje oluşturun
Proje ayarlarından project UUID ve API key değerlerini alın
Çekim özelliğini kullanmayı planlıyorsanız ayrı bir Payout API key oluşturun
İsteklerin nasıl imzalanacağını öğrenmek için Authentication bölümünü okuyun
İlk Create Payment çağrınızı yapın

Base URL

Tüm production API istekleri aşağıdaki base URL'i kullanır:

Text

https://api.2328.io/api

Tüm istekler HTTPS üzerinden yapılmalıdır. HTTPS kullanmayan istekler engellenir.

Neler yapabilirsiniz

2328.io API ile şunları yapabilirsiniz:

Kripto ödemeleri kabul edin — ödeme oturumları oluşturun ve müşterileri hosted checkout veya Telegram MiniApp'e yönlendirin
Para çekin — merchant bakiyenizden herhangi bir blockchain adresine programatik olarak çekim yapın
Bakiye sorgulama — para birimi başına satıcı hesap bakiyelerini, USD karşılıklarını ve AML tarafından kilitlenen tutarları görün
Statik cüzdanlar kullanın — bir kullanıcıya veya siparişe bağlı kalıcı yatırma adresleri oluşturun
Döviz kurlarını alın — fiat ve kripto çiftleri için gerçek zamanlı kurları alın
Webhook alın — ödeme durumu değiştiğinde anında bildirim alın

Hız limitleri

API, proje başına saniyede 10 isteğe kadar izin verir. Limiti aşan istekler HTTP 429 Too Many Requests yanıtı alır — geri çekilin ve yeniden deneyin.

Doğru entegrasyon desenini seçin

Gereksinim	Önerilen desen	Neden
Müşterinin nasıl ödeyeceğini seçmesine izin verin	Hosted checkout	Bir ödeme oluşturun ve `result.url`'ya yönlendirin; 2328.io şu anda mevcut yönleri gösterir.
Müşteriyi kendi ödeme sayfanız içinde tutun	Doğrudan adres H2H invoice	Ödeme oluştururken `to_currency` ve `network` gönderin; döndürülen `address`, `payer_amount` ve `qr`'yi görüntüleyin.
Tam olarak `25 USDT` veya `0.001 BTC` tahsil edin	Kripto para birimi cinsinden invoice	Kripto para birimini `currency`'ya koyun ve tam ondalık miktarı `amount`'ye girin.
Her kullanıcıya tekrar kullanılabilir bir depozito adresi verin	Static wallet	Adres kalıcıdır ve birçok bağımsız depozitoyu alabilir.
Gelen varlıkları tek bir bakiye para birimine normalleştirin	Auto-convert	Proje kurallarını kontrol panelinde yapılandırın ve dönüşüm tamamlandığında `convert` sonucunu kullanın.
Mevcut bir merchant bakiyesini değiştirin	Manual convert	`/v1/convert/price` ile önizleyin, sonra `/v1/convert` ile yürütün.
Fonları bir blok zinciri adresine gönderin	Ödeme	Ayrı Payout API anahtarını kullanın, önce hesaplayın ve ödeme durumunu mutabakata bağlayın.

Hosted checkout ve H2H aynı Payment API’nin iki sunumudur. H2H daha zayıf veya imzasız bir ödeme oluşturmaz: backend yine invoice oluşturur, 2328.io yine adres ve durumu elinde tutar ve imzalı webhooks settlement için otoriter kalır.

Entegrasyon sabitleri

Bu kurallar her production entegrasyonu için geçerlidir:

Yalnızca Backend — API anahtarlarını tarayıcılar, mobil uygulamalar, günlükler, analizler ve destek ekran görüntülerinden uzak tutun.
Ondalık dizgiler — parayı dizge olarak gönderin ve saklayın. Kripto para birimi veya döviz kurları ile ikili kayan nokta aritmetiği kullanarak asla yuvarlama yapmayın.
Değiştirilemez idempotency anahtarları — ilk isteğin öncesinde order_id oluşturun ve istekle birlikte tüm isteği saklayın. Aynı order_id ile bir retry, değiştirilen alanları uygulamak yerine orijinal nesneyi döndürebilir.
Webhook-öncelikli settlement — yönlendirmeler, istemci yoklamaları, kullanıcı tarafından sağlanan işlem karmaları ve HTTP zaman aşımı ödeme kanıtı değildir.
Doğrula, yineleneni kaldır, sonra değiştir — HMAC’i doğrulayın, bir idempotency kaydını atomik olarak talep edin, siparişi/bakiye güncelleyin ve HTTP 200’ü hızlıca döndürün.
Reconciliation — kaybolan webhook kalıcı anlaşmazlığa yol açmasın diye ödeme, statik cüzdan ve ödeme durumunu periyodik olarak sorgulayın.
Dinamik kullanılabilirlik — para birimi/ağ çiftlerini /v1/directions ile doğrulayın; desteklenen bir varlık yine de tek yönlü bir yatırma veya çekme işlemi geçici olarak devre dışı olabilir.
Açık durum politikası — ürününüzün kısmi ödeme, fazla ödeme, süresi dolmuş işlem, AML kilidi, dönüştürme fallback ve belirsiz üst akış zaman aşımı durumlarını canlıya geçmeden önce nasıl yöneteceğine karar verin.

Saklanması önerilen veriler

Ödemeler için en az uuid, order_id, orijinal istek gövdesi, amount, currency, payer_currency, payer_amount, network, address, expires_at, en son payment_status, txid, payment_amount, merchant_amount, isteğe bağlı convert bloğu ve doğrulanmış ham webhook payload saklayın.

static wallets için cüzdanı uuid, adresi, para birimini, ağı, müşteri/hesap referansını, durumu ve geri arama URL'sini mevduat kayıtlarından ayrı tutun. Her mevduat kendi işlem uuid, txid, durumu, alınan miktarı, merchant miktarı ve dönüşüm sonucuna sahip olmalıdır.