開発者ドキュメント

支払い結果と注文状態を照会

販売者注文 ID で照会し、支払い確認・通知配信・商品提供を区別します。

POST /api/v1/order/status

認証をリクエスト

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

01. リクエストパラメータ

application/json
externalOrderId必須
String

注文の作成時に使用した販売者 orderToken ではなく、externalOrderId を送信します。現在の API キーに属する注文のみをクエリできます。

値の例

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

必須の文字列、6 ～ 64 文字。文字、数字、アンダースコア (_)、およびハイフン (-) を使用できます。

Body

注文の状態と履行

PENDING

支払い待ち: 一致する対象となる送金がありません。

PAID

支払いが検出され、ブロックチェーンの確認を待っています。

CONFIRMED

販売者の審査を通じて支払いが確認または受理されました。コールバック配信はまだ保留中の可能性があります。

COMPLETED

支払いが確認され、BoltUtil が正常なコールバック応答を受け取りました。

EXPIRED

支払い期間は、一致する適格な送金が行われずに終了しました。確認が遅れたオンタイム転送でも、後で認識される可能性があります。

FAILED

注文は失敗した状態です。これを支払いの成功として扱わないでください。

CANCELLED

注文はキャンセルされました。これを支払いの成功として扱わないでください。

PAID は確認待ちなので、この状態だけで商品を提供しないでください。CONFIRMED または COMPLETED は支払確認済みを示します。externalOrderId ごとに一度だけ提供してください。COMPLETED は BoltUtil が通知への成功応答を受け取ったことを示し、加盟店による提供完了の証明ではありません。手動審査した支払では実払金額と決済種別も確認してください。

02. 応答フィールド (data)

application/json
statusString
現在の注文状態。上記の状態の説明を参照してください。注文はすべての州を通過する必要はありません。
amountString
支払可能な注文金額。文字列として返されます。記録された支払額には paidAmount を使用します。
paidAmountString / null
支払った金額を文字列として記録します。支払い前は null になる場合があります。別の支払い金額のない古い支払い済みの注文の場合、支払可能な金額に戻ります。
shortfallAmountString / null
不足分を文字列として記録。支払い前は null になる場合があります。手動で承認された過払いは、ここで 0 を返す場合があります。符号付きの差を計算するには、amount から paidAmount を減算します。
settlementTypeString / null
EXACT: 完全一致。 MANUAL_UNDERPAID: 過少支払いを受け入れました。 MANUAL_OVERPAID: 過払いを受け入れました。 MANUAL_AMBIGUOUS: 手動でレビューされた別の関連付け。決済前は null になる可能性があります。
manuallyAcceptedBoolean
現在、true は MANUAL_UNDERPAID のみです。すべての手動アクションを識別するわけではありません。特定のタイプには settlementType を使用します。
externalOrderIdString
作成時に指定された販売者注文 ID。ビジネス注文のクエリと関連付けに使用されます。
txHashString / null
関連する支払いのトランザクション ハッシュ。関連付け前は null である可能性があります。ハッシュだけでは支払いの確認を証明できません。
destinationAddressString
この注文で使用される販売者受け取りウォレット。複数の注文がそれを共有する場合があります。
confirmationsInteger / null
記録されたブロックチェーン確認数。 null の場合があります。確認ルールはネットワークごとに異なります。 status を使用して支払いの確認を決定します。
currencyString
支払い通貨コード (USDT や USDC など)。
networkString
支払いネットワーク コード: TRC20、ERC20、BEP20、POLYGON、SOLANA または BASE。
paidAtString / null
支払い時刻を日時文字列として記録します。支払いが記録される前の null。
confirmedAtString / null
支払い確認時刻を日時文字列として記録します。確認前は null。
completedAtString / null
注文が最初に入力された時刻 COMPLETED (日時文字列)。完了前はnull。繰り返し配信が成功しても上書きされません。以前に完了した注文には、履歴に記録された時間が保持されます。
metadataObject
注文作成時に指定されたカスタム JSON オブジェクト。支払い照合には使用されません。

クエリメモ

  • クエリは保存された注文の状態を返します。ブロックチェーンはすぐにはスキャンされません。確認値は記録された値です。 status を使用して支払いの確認を決定します。
  • 支払いが一致しない場合、paidAmount、shortfallAmount、settlementType、txHash、および関連する時間は null になる可能性があります。これはクエリの失敗ではありません。
  • 自分の注文のみを照会できます。無料アカウントは、過去 30 日以内に作成された注文にアクセスできます。アクティブなメンバーはすべての履歴にアクセスできます。注文が見つからない、またはアクセスできない場合、注文が見つかりません。
  • paidAt、confirmedAt、および completedAt は、タイムゾーン オフセットを含まない日付時刻文字列 (2026-02-09T18:20:50.790 など) です。これらはミリ秒のタイムスタンプではありません。

一般的なエラー

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

  • 401: API キー、生の本体署名、および現在のミリ秒 timestamp (サーバー クロックの 5 分以内) を確認します。
  • 404: 注文が見つからないか、別の販売者に属しているか、プランで許可されている履歴の範囲外です。
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"

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

Base URL

PROD
https://api.boltutil.com