Geliştirici belgeleri

Ödeme ve sipariş durumunu sorgulama

Satıcı sipariş ID’siyle sorgulayın. Onay, bildirim teslimi ve sipariş teslimatını ayırın.

POST /api/v1/order/status

Kimlik doğrulama iste

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

01. İstek parametreleri

application/json
externalOrderIdGerekli
String

Siparişi oluştururken kullanılan orderToken satıcısını değil, externalOrderId satıcısını gönderin. Yalnızca mevcut API anahtarına ait siparişler sorgulanabilir.

Örnek değer

{"externalOrderId": "INV-20260209-99281"}

Gerekli dize, 6-64 karakter. Harflere, rakamlara, alt çizgilere (_) ve kısa çizgilere (-) izin verilir.

Body

Sipariş durumları ve yerine getirilmesi

PENDING

Ödeme bekleniyor: uygun transfer bulunamadı.

PAID

Ödeme algılandı, blockchain onayı bekleniyor.

CONFIRMED

Ödeme satıcı incelemesi yoluyla onaylandı veya kabul edildi; Geri arama teslimi hâlâ beklemede olabilir.

COMPLETED

Ödeme onaylandı ve BoltUtil başarılı bir geri arama yanıtı aldı.

EXPIRED

Ödeme penceresi, eşleşen uygun bir transfer olmadan sona erdi. Onaylanması gecikmeli olan zamanında yapılan bir transfer daha sonra da fark edilebilir.

FAILED

Sipariş başarısız durumda. Bunu ödeme başarısı olarak görmeyin.

CANCELLED

Sipariş iptal edildi. Bunu ödeme başarısı olarak görmeyin.

PAID, onayın beklendiğini belirtir; bu duruma dayanarak teslimat yapmayın. CONFIRMED veya COMPLETED, ödemenin onaylandığını gösterir; her externalOrderId için yalnızca bir kez teslim edin. COMPLETED, BoltUtil’ın bildirime başarılı yanıt aldığı anlamına gelir; işletmenizin teslimatı tamamladığını kanıtlamaz. Elle incelenen ödemelerde ödenen tutarı ve uzlaştırma türünü de kontrol edin.

02. Yanıt alanları (data)

application/json
statusString
Geçerli sipariş durumu. Yukarıdaki durum açıklamalarına bakın; bir emrin her eyaletten geçmesi gerekmez.
amountString
Dize olarak döndürülen ödenecek sipariş tutarı. Kaydedilen ödenen tutar için paidAmount kullanın.
paidAmountString / null
Ödenen tutar dize olarak kaydedildi; ödemeden önce null olabilir. Ayrı bir ödenen tutar bulunmayan daha eski ücretli siparişler için ödenecek tutara düşer.
shortfallAmountString / null
Dize olarak kaydedilen eksiklik; ödemeden önce null olabilir. Manuel olarak kabul edilen fazla ödemeler burada 0 değerini döndürebilir. İmzalı farkı hesaplamak için paidAmount'yi amount'den çıkarın.
settlementTypeString / null
EXACT: tam eşleşme; MANUAL_UNDERPAID: eksik ödeme kabul edildi; MANUAL_OVERPAID: kabul edilen fazla ödeme; MANUAL_AMBIGUOUS: manuel olarak incelenen başka bir ilişkilendirme. Ödemeden önce null olabilir.
paymentRouteString / null
Gerçek ödeme yolu: doğrudan transfer DIRECT, bölünmüş ödeme SPLIT. Hesaplaşmadan önce sorguda null olabilir; ödeme onayı değildir.
platformFeeString / null
currency cinsinden gerçek platform ücreti, metin olarak döner; kaydedilmeden önce null olabilir. Doğrudan veya muaf ödemelerde 0’dır. Ağ ücreti hariçtir.
merchantNetAmountString / null
currency cinsinden satıcı net tahsilatı, metin olarak. Bölünmüş ödemede toplam ödenen eksi platform ücreti. Kayıt öncesi null olabilir; eski callback’ler ödenen tutarı kullanabilir.
manuallyAcceptedBoolean
Şu anda true yalnızca MANUAL_UNDERPAID için. Her manuel eylemi tanımlamaz; belirli tür için settlementType kullanın.
externalOrderIdString
İş siparişinizi sorgulamak ve ilişkilendirmek için kullanılan, oluşturma sırasında sağlanan satıcı siparişi ID.
txHashString / null
İlişkili ödemenin işlem karması; ilişkilendirmeden önce null olabilir. Karma tek başına ödeme onayını kanıtlamaz.
destinationAddressString
Bu sipariş tarafından kullanılan cüzdanı alan satıcı; birden fazla sipariş bunu paylaşabilir.
confirmationsInteger / null
Kayıtlı blockchain onay sayısı; null olabilir. Onay kuralları ağa göre farklılık gösterir. Ödeme onayını belirlemek için status kullanın.
currencyString
USDT veya USDC gibi ödeme para birimi kodu.
networkString
Ödeme ağı kodu: TRC20, ERC20, BEP20, POLYGON, SOLANA veya BASE.
paidAtString / null
Tarih-saat dizesi olarak kaydedilen ödeme süresi; null ödeme kaydedilmeden önce.
confirmedAtString / null
Tarih-saat dizesi olarak kaydedilen ödeme onay zamanı; Onaylamadan önce null.
completedAtString / null
COMPLETED emrinin ilk girildiği zaman, tarih-saat dizesi olarak; null tamamlanmadan önce. Başarılı tekrar teslimi bunun üzerine yazmaz. Daha önce tamamlanan siparişlerin geçmiş kayıtlı süreleri korunur.
metadataObject
Sipariş oluşturulurken sağlanan özel JSON nesnesi. Ödeme eşleştirme için kullanılmaz.

Sorgu notları

  • Sorgu, saklanan siparişin durumunu döndürür; blok zincirini hemen taramaz. Onaylar kaydedilen değerlerdir. Ödeme onayını belirlemek için status kullanın.
  • Eşleşen bir ödeme olmadan, paidAmount, shortfallAmount, settlementType, txHash ve ilgili zamanlar null olabilir. Bu bir sorgu hatası değildir.
  • Yalnızca kendi siparişleriniz sorgulanabilir. Ücretsiz hesaplar, son 30 gün içinde oluşturulan siparişlere erişebilir; aktif üyeler tüm geçmişe erişebilir. Eksik veya erişilemeyen siparişlerin iade emri bulunamadı.
  • paidAt, confirmedAt ve completedAt, saat dilimi farkı olmayan 2026-02-09T18:20:50.790 gibi tarih-saat dizeleridir. Bunlar milisaniyelik zaman damgaları değildir.

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.
  • 404: Sipariş eksik, başka bir satıcıya ait veya planınızın izin verdiği geçmişin dışında.
status / 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='{"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/status" \
  --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