開発者ドキュメント

ステーブルコインの支払い注文を作成

サーバーから署名付き API リクエストで USDT・USDC 注文を作成。必須項目、ネットワーク、正確な支払額、決済 URL、有効期限、Webhook 設定を確認し、注文番号を保存して決済画面を表示します。

POST /api/v1/order/create

認証が必要です

X-Bolt-Key、X-Bolt-Timestamp、X-Bolt-Signature を含めます。現在のミリ秒 timestamp を使用し、正確な生のリクエスト本文とともに timestamp に署名します。

USDTUSDC

金額の正確な一致

API が返す支払金額が少し高くなるのはなぜですか？

立ち上げ計画

3 つの固定数字

ビジネスプロ

2 ～ 6 で構成可能

設定した識別桁数に合わせて金額を切り上げます。同じネットワーク、通貨、受取ウォレットで同額の未払い注文がある場合、新しい注文を区別するため小さな差額を加算します。支払予定額が元の金額を下回ることはありません。無料アカウントは 3 桁固定、Pro 会員は 2–6 桁を選べます。応答の payment.amount を使用してください。

マッチングの流れ

注文の作成

1

amount

バックエンドが決済金額を送信し、BoltUtil が支払い可能なオンチェーン金額を返します。

チェックアウトを表示

2

payment.amount

正確な返金額、ネットワーク、受信アドレスを支払者に表示します。

オンチェーン支払の照合

3

Webhook

モニターは、ネットワーク、アドレス、トークン、金額、注文ステータスに基づいて照合してから、通知します。

統合メモ

1

リクエスト金額や元の商品価格ではなく、注文作成レスポンスから payment.amount を表示します。

2

支払い指示を表示するときは、小数点以下のオフセットを四捨五入したり、切り捨てたり、削除したりしないでください。

3

オフセット精度の変更は、新しく作成された注文にのみ影響し、既存の未決注文には影響しません。

4

externalOrderId で履行し、支払いステータスを確認する前に、Webhook 署名を検証し、通知の重複を排除します。確認待ちの支払いは支払い成功ではありません。

01. リクエスト本文

JSON Payload
amount
必須
Decimal

currency で指定された通貨での元の商品またはビジネス注文の金額。浮動小数点精度の損失を避けるために文字列を送信します。支払者は、この値ではなく、返された payment.amount を支払う必要があります。

基本の最低金額は 1.00 です。選択したネットワークと通貨に設定された最低金額も満たす必要があります。精度制限: 小数点以下 6 桁までセキュリティ リスク: フロントエンドで計算される通過額は厳しく禁止されています。常にバックエンド データベースから値を取得します。
externalOrderId
必須
String

ビジネス注文 ID。BoltUtil 注文を関連付けるために使用されます。クエリでは externalOrderId を使用します。作成応答は merchantExternalId を返し、Webhooks は externalOrderId を返します。

販売者ごとにグローバルに一意である必要がありますサポートされている文字: 文字、数字、アンダースコア (_)、ハイフン (-)長さ制限: 6 ～ 64 文字重複した ID は、既存の注文ではなくエラーを返します。
network
必須
String

以下の大文字の値のいずれかを使用して支払いネットワークを選択します。たとえば、Base の場合は BASE、Ethereum の場合は ERC20 を使用します。

値の例

"network": "BASE"
許可される値: TRC20、ERC20、BEP20、POLYGON、SOLANA、BASEチェックアウト時に同じネットワークを表示します。
currency
必須
String

支払い通貨を選択します。 USDT または USDC のみを渡します。ネットワークはnetworkで別途指定してください。

値の例

"currency": "USDC"
許可される値: USDT、USDC⚠️ TRC20 は USDT のみをサポートします。他のペアには、有効なルートと有効な受信ウォレットが必要です。
orderDesc
String

注文記録のオプションの製品またはビジネスの概要。現在のチェックアウトにはこのフィールドは表示されません。

推奨される形式: トップアップ - [ユーザー アカウント]最大長: 255 文字
notifyUrl
URL

Webhook この注文の受信者。省略した場合、販売者ダッシュボードで有効になっているデフォルトのアドレスが使用されます。

HTTPS である必要がありますパブリックにアクセスできる必要があります不変: この URL は、注文が作成されると変更できません。注文を作成する前に、ダッシュボードで Webhook と署名シークレットを構成して有効にします。このパラメータはその設定を置き換えません。最大長: 255 文字
returnUrl
URL

支払いが完了するか、ユーザーが戻ることを選択すると、チェックアウトによりブラウザがこの URL にリダイレクトされます。これは単なるナビゲーション目的地であり、支払いの成功を証明するものではありません。

署名済み Webhook または注文状況クエリを通じて支払いを確認する省略した場合、デフォルトは https://boltutil.com です。最大長: 255 文字
expiredMinutes
Long

注文が作成された後、その注文が支払われるまでの時間（分）。無料プランは 30 分に固定されています。プロメンバーは 15 ～ 60 分を選択できます。

設定可能な範囲: 15 ～ 60 分デフォルト: 30 分この値をカスタマイズできるのは Pro メンバーのみです。無料プランは 30 分に固定されています無料アカウントでは、有効範囲内のカスタム値は無視され、30 分が使用されます。実際の有効期限として time.expireTimestamp を使用します。
metadata
Map

販売者定義の JSON data。 BoltUtil は変更せず、注文作成応答、注文ステータス応答、および Webhook で変更せずに返します。

形式: 標準 JSON オブジェクト変更せずに返され、支払い照合には使用されません最大 10 個のトップレベル キー

02. 応答の詳細

application/json
orderToken
BoltUtil チェックアウトを開くための注文識別子。販売者の API クエリは externalOrderId を使用します。
merchantExternalId
リクエストの externalOrderId に対応します。
status
PENDING。後の支払いとコールバックの状態については、注文ステータスのドキュメントを参照してください。
注文状態の照会 →
checkoutUrl
専用のチェックアウト支払いリンク。
returnUrl
チェックアウトの返送先住所。省略した場合のデフォルトは https://boltutil.com です。
metadata
カスタム パススルー data オブジェクト。

data.payment { ... }

address
この注文で使用される販売者受け取りウォレット。複数の注文がこのアドレスを共有する場合があります。注文ごとに新しいアドレスは生成されません。
amount
文字列として返される正確な支払額。四捨五入や切り捨てをせずに完全に表示します。
rawAmount
最小トークン単位の金額。整数文字列として返されます: payment.amount × 10^payment.decimal。 decimal = 6 の場合、1 トークンは 1,000,000 最小単位に相当します。
currency
通貨記号。
network
ネットワーク識別子。
qrData
支払用 QR コードを生成するためのアドレス文字列です。金額、通貨、ネットワークは含まれません。payment.amount、currency、network は別途表示してください。
decimal
rawAmount の換算に使う、このネットワーク上のトークンの桁数です。注文金額を区別するための桁数とは異なります。

data.time { ... }

expireTimestamp
data.time: 有効期限を Unix ミリ秒 timestamp として注文します。
serverTimestamp
data.time: 応答が生成されたときのサーバー時間 (Unix ミリ秒 timestamp)。

一般的なエラー

これらは一般的なケースです。実際の HTTP ステータスと応答コード/メッセージを使用して、障害を診断します。エラー応答は支払い結果ではありません。

  • 401: API キー、生の本体署名、および現在のミリ秒 timestamp (サーバー クロックの 5 分以内) を確認します。
  • 400: externalOrderId はすでに存在します。重複した業務注文を作成する代わりに、元の注文を照会します。
  • 400: 必須パラメータ、利用可能なネットワーク/アセット、受信ウォレット、有効な Webhook 設定を確認してください。
  • 429：リクエスト頻度制限、または無料枠の1日あたりの注文作成数を超えています。業務エラーコードと message を確認してください。
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"

アドレス、トランザクション ハッシュ、注文は例です。これらを独自のテスト data に置き換えます。

Base URL

PROD
https://api.boltutil.com