Geliştirici belgeleri

Stablecoin ödeme siparişi oluşturma

İmzalı API istekleriyle sunucunuzdan USDT / USDC siparişi oluşturun. Alanları, ağı, tam tutarı, ödeme bağlantısını, süreyi ve Webhook ayarlarını kontrol edin.

POST /api/v1/order/create

Kimlik Doğrulaması Gerekli

X-Bolt-Key, X-Bolt-Timestamp ve X-Bolt-Signature'yi dahil edin. Geçerli bir milisaniye timestamp kullanın ve timestamp'yi tam ham istek gövdesiyle birlikte imzalayın.

USDTUSDC

Tam tutar eşleşmesi

API’nin döndürdüğü ödeme tutarı neden biraz daha yüksek olabilir?

Başlatma planı

3 sabit rakam

İşletme Uzmanı

2-6 yapılandırılabilir

Sistem tutarı yapılandırılmış ayırt etme hassasiyetine göre yukarı yuvarlar. Aynı ağ, para birimi ve alıcı cüzdanda bu tutarı kullanan başka bir bekleyen sipariş varsa yeni siparişi ayırt etmek için küçük bir fark ekler. Ödenecek tutar özgün tutardan az olmaz. Ücretsiz hesaplar 3 basamak kullanır; Pro üyeleri 2–6 basamak seçebilir. Yanıttaki payment.amount değerini kullanın.

Eşleşen akış

Sipariş oluştur

1

amount

Arka ucunuz uzlaşma tutarını gönderir ve BoltUtil, zincir üzerinde ödenecek tutarı döndürür.

Ödemeyi göster

2

payment.amount

Ödeyiciye iade edilen tutarı, ağı ve alıcı adresini tam olarak görüntüleyin.

Zincir üzerindeki ödemeyi eşleştirme

3

Webhook

İzleyici, size bildirimde bulunmadan önce ağ, adres, belirteç, tutar ve sipariş durumuna göre eşleştirme yapar.

Entegrasyon notları

1

İstek tutarını veya orijinal ürün fiyatını değil, sipariş oluşturma yanıtındaki payment.amount'yi görüntüleyin.

2

Ödeme talimatlarını gösterirken küçük ondalık farkı yuvarlamayın, kesmeyin veya kaldırmayın.

3

Ofset hassasiyetinin değiştirilmesi yalnızca yeni oluşturulan siparişleri etkiler, mevcut bekleyen siparişleri etkilemez.

4

externalOrderId'ye kadar tamamlamadan ve ödeme durumunu onaylamadan önce Webhook imzasını doğrulayın ve bildirimleri tekilleştirin. Onay bekleyen bir ödeme, ödemenin başarılı olduğu anlamına gelmez.

01. İstek Gövdesi

JSON Payload
amount
Gerekli
Decimal

currency tarafından belirtilen para birimi cinsinden orijinal ürün veya iş siparişi tutarı. Kayan nokta hassasiyeti kaybını önlemek için bir dize gönderin. Ödemeyi yapanın bu değer yerine iade edilen payment.amount tutarını ödemesi gerekir.

Temel alt sınır: 1.00. Seçilen ağ ve para birimi için yapılandırılan alt sınır da karşılanmalıdır.Hassaslık sınırı: En fazla 6 ondalık basamakGüvenlik Riski: Ön uçta hesaplanan tutarların aktarılmasını kesinlikle yasaklayın. Değerleri her zaman arka uç veritabanınızdan alın.
externalOrderId
Gerekli
String

BoltUtil siparişini ilişkilendirmek için kullanılan iş siparişiniz ID. Sorgular externalOrderId'yi kullanır; oluşturma yanıtı merchantExternalId'yi döndürür ve Webhooks, externalOrderId'yi döndürür.

Satıcı başına dünya çapında benzersiz olmalıdırDesteklenen: Harfler, sayılar, alt çizgiler (_), kısa çizgiler (-)Uzunluk sınırı: 6 - 64 karakterID kopyası, mevcut sipariş yerine hata döndürür.
network
Gerekli
String

Aşağıdaki büyük harf değerlerinden birini kullanarak bir ödeme ağı seçin. Örneğin, Base için BASE'yi veya Ethereum için ERC20'yi kullanın.

Örnek değer

"network": "BASE"
İzin verilen değerler: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEÖdemede aynı ağı göster.
currency
Gerekli
String

Ödeme para birimini seçin. Yalnızca USDT veya USDC'yi geçin; ağı network'de ayrı olarak belirtin.

Örnek değer

"currency": "USDC"
İzin verilen değerler: USDT, USDC⚠️ TRC20 yalnızca USDT'yi destekler. Diğer çiftler etkin bir rotaya ve geçerli bir alıcı cüzdana ihtiyaç duyar.
orderDesc
String

Sipariş kayıtları için isteğe bağlı ürün veya işletme özeti. Geçerli ödemede bu alan görüntülenmiyor.

Önerilen format: Yükleme - [Kullanıcı Hesabı]Maksimum uzunluk: 255 karakter
notifyUrl
URL

Bu sipariş için Webhook alıcı. Atlanırsa satıcı kontrol panelinizde etkin olan varsayılan adres kullanılır.

HTTPS olmalıdırHerkese açık olmalıdırDeğişmez: Bu URL, sipariş oluşturulduktan sonra değiştirilemez.Bir sipariş oluşturmadan önce, kontrol panelinizde Webhook ve imzalama sırrını yapılandırıp etkinleştirin. Bu parametre söz konusu yapılandırmanın yerini almaz.Maksimum uzunluk: 255 karakter
returnUrl
URL

Ödeme tamamlandıktan veya kullanıcı geri dönmeyi seçtikten sonra, ödeme işlemi tarayıcıyı bu URL'ye yönlendirir. Bu yalnızca bir navigasyon hedefidir ve ödemenin başarılı olduğunu kanıtlamaz.

İmzalı Webhook veya sipariş durumu sorgusu aracılığıyla ödemeyi doğrulayınAtlanırsa varsayılan https://boltutil.com'dir.Maksimum uzunluk: 255 karakter
expiredMinutes
Long

Bir siparişin oluşturulduktan sonra ödenebilir kalacağı dakika sayısı. Ücretsiz plan 30 dakika olarak sabitlenmiştir; Profesyonel üyeler 15-60 dakika arasında seçim yapabilir.

Yapılandırılabilir aralık: 15-60 dakikaVarsayılan: 30 dakikaYalnızca Pro üyeler bu değeri özelleştirebilir; ücretsiz planın süresi 30 dakika olarak sabitlenmiştirÜcretsiz hesaplar, geçerli aralıktaki özel değerleri yok sayar ve 30 dakikayı kullanır. Gerçek son kullanma tarihi olarak time.expireTimestamp'yi kullanın.
metadata
Map

Satıcı tarafından tanımlanan JSON data. BoltUtil bunu değiştirmez ve sipariş oluşturma yanıtında, sipariş durumu yanıtında ve Webhook'de değişmeden döndürür.

Biçim: standart JSON nesnesiDeğiştirilmeden iade edildi ve hiçbir zaman ödeme eşleştirmesi için kullanılmadıEn fazla 10 üst düzey anahtar

02. Yanıt Ayrıntıları

application/json
orderToken
BoltUtil Ödemeyi açmaya yönelik sipariş tanımlayıcı. Satıcı API sorguları externalOrderId'yi kullanır.
merchantExternalId
İstekteki externalOrderId'ye karşılık gelir.
status
PENDING başarıyla oluşturulduktan sonra. Daha sonraki ödeme ve geri arama durumları için sipariş durumu belgelerine bakın.
Sipariş durumunu sorgulama →
checkoutUrl
Özel ödeme ödeme bağlantısı.
returnUrl
Ödeme iade adresi. Atlanırsa varsayılan olarak https://boltutil.com olur.
metadata
Özel geçiş data nesnesi.

data.payment { ... }

address
Bu sipariş tarafından kullanılan cüzdanı alan satıcı. Birden fazla sipariş bu adresi paylaşabilir; sipariş başına yeni adres oluşturulmaz.
amount
Tam ödenecek tutar, dize olarak döndürülür. Yuvarlamadan veya kesmeden tam olarak görüntüleyin.
rawAmount
Tamsayı dizesi olarak döndürülen en küçük jeton birimindeki tutar: payment.amount × 10^payment.decimal. decimal = 6 için bir jeton 1.000.000 en küçük birime eşittir.
currency
Para birimi simgesi.
network
Ağ tanımlayıcı.
qrData
Ödeme QR kodu oluşturmak için adres metni. Tutar, para birimi veya ağ içermez. payment.amount, currency ve network alanlarını ayrıca gösterin.
decimal
rawAmount dönüşümünde kullanılan, seçilen tokenin bu ağdaki basamak sayısıdır. Sipariş tutarlarını ayırt etmek için kullanılan hassasiyet değildir.

data.time { ... }

expireTimestamp
data.time'de: siparişin sona ermesi Unix milisaniye timestamp olarak.
serverTimestamp
data.time'de: Unix milisaniye timestamp olarak yanıtın oluşturulduğu sunucu zamanı.

Genel hatalar

Bunlar yaygın görülen durumlardır. Arızaları teşhis etmek için gerçek HTTP durumunu ve yanıt kodunu/mesajını kullanın. Hata yanıtı bir ödeme sonucu değildir.

  • 401: API Anahtarını, ham gövde imzasını ve mevcut milisaniye timestamp'yi (sunucu saatinden sonraki 5 dakika içinde) kontrol edin.
  • 400: externalOrderId zaten mevcut. Yinelenen bir iş emri oluşturmak yerine orijinal siparişi sorgulayın.
  • 400: Gerekli parametreleri, kullanılabilir ağı/varlığı, alma cüzdanını ve etkin Webhook yapılandırmasını kontrol edin.
  • 429: İstek hız sınırı veya ücretsiz günlük sipariş oluşturma kotası aşıldı. İş hata kodunu ve message alanını kontrol edin.
create / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Adresler, işlem karmaları ve siparişler örnektir. Bunları kendi testiniz data ile değiştirin.

Base URL

PROD
https://api.boltutil.com