Developer documentation

Query payment results and order status

Query recorded payment results by merchant order ID. Distinguish pending confirmation, confirmed payment and successful callback delivery.

POST /api/v1/order/status

Request authentication

Include X-Bolt-Key, X-Bolt-Timestamp and X-Bolt-Signature. Use a current millisecond timestamp and sign the timestamp together with the exact request body.

01. Request parameters

application/json
externalOrderIdRequired
String

Send the merchant externalOrderId used when creating the order, not orderToken. Only orders belonging to the current API key can be queried.

Example value

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

Required string, 6–64 characters. Letters, digits, underscores (_) and hyphens (-) are allowed.

Body

Order states and fulfillment

PENDING

Awaiting payment: no eligible transfer has been matched.

PAID

Payment detected, awaiting blockchain confirmation.

CONFIRMED

Payment confirmed or accepted through merchant review; callback delivery may still be pending.

COMPLETED

Payment confirmed and BoltUtil has received a successful callback response.

EXPIRED

The payment window ended without a matched eligible transfer. An on-time transfer with delayed confirmation may still be recognized later.

FAILED

The order is in a failed state. Do not treat it as payment success.

CANCELLED

The order was cancelled. Do not treat it as payment success.

PAID is awaiting confirmation and must not trigger fulfillment. CONFIRMED or COMPLETED means payment has been confirmed; fulfill only once per externalOrderId. COMPLETED means BoltUtil received a successful callback response, not that your business actually fulfilled the order. For reviewed payments, also check the paid amount and settlement type.

02. Response fields (data)

application/json
statusString
Current order state. See the state descriptions above; an order need not pass through every state.
amountString
The payable order amount, returned as a string. Use paidAmount for the recorded paid amount.
paidAmountString / null
Recorded paid amount as a string; may be null before payment. For older paid orders without a separate paid amount, it falls back to the payable amount.
shortfallAmountString / null
Recorded shortfall as a string; may be null before payment. Manually accepted overpayments may return 0 here. To calculate a signed difference, subtract paidAmount from amount.
settlementTypeString / null
EXACT: exact match; MANUAL_UNDERPAID: accepted underpayment; MANUAL_OVERPAID: accepted overpayment; MANUAL_AMBIGUOUS: another manually reviewed association. May be null before settlement.
paymentRouteString / null
Actual payment route: DIRECT for direct transfer, SPLIT for split payment. Queries may return null before settlement; this field is not payment confirmation.
platformFeeString / null
Actual platform fee in currency, returned as a string; queries may return null before it is recorded. Direct or fee-exempt payments use 0. Network fees are excluded.
merchantNetAmountString / null
Merchant net receipts in currency, as a string. For split payments, gross paid amount minus platform fee. Queries may return null before recording; historical callbacks may fall back to paid amount.
manuallyAcceptedBoolean
Currently true only for MANUAL_UNDERPAID. It does not identify every manual action; use settlementType for the specific type.
externalOrderIdString
Merchant order ID supplied at creation, used to query and associate your business order.
txHashString / null
Transaction hash of the associated payment; may be null before association. A hash alone does not prove payment confirmation.
destinationAddressString
The merchant receiving wallet used by this order; multiple orders may share it.
confirmationsInteger / null
Recorded blockchain confirmation count; may be null. Confirmation rules differ by network. Use status to determine payment confirmation.
currencyString
Payment currency code, such as USDT or USDC.
networkString
Payment network code: TRC20, ERC20, BEP20, POLYGON, SOLANA or BASE.
paidAtString / null
Recorded payment time as a date-time string; null before a payment is recorded.
confirmedAtString / null
Recorded payment confirmation time as a date-time string; null before confirmation.
completedAtString / null
Time the order first entered COMPLETED, as a date-time string; null before completion. Successful repeat delivery does not overwrite it. Previously completed orders retain their historical recorded time.
metadataObject
Custom JSON object supplied at order creation. It is not used for payment matching.

Query notes

  • The query returns stored order state; it does not immediately scan the blockchain. Confirmations are recorded values. Use status to determine payment confirmation.
  • Without a matched payment, paidAmount, shortfallAmount, settlementType, txHash and related times may be null. This is not a query failure.
  • Only your own orders can be queried. Free accounts can access orders created within the last 30 days; active members can access all history. Missing or inaccessible orders return order not found.
  • paidAt, confirmedAt and completedAt are date-time strings, such as 2026-02-09T18:20:50.790, without a timezone offset. They are not millisecond timestamps.

Common errors

These are common cases. Use the actual HTTP status and response code/message to diagnose failures. An error response is not a payment result.

  • 401: Check the API Key, raw-body signature and current millisecond timestamp (within 5 minutes of the server clock).
  • 404: The order is missing, belongs to another merchant or is outside the history allowed by your plan.
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"

Addresses, transaction hashes and orders are examples. Replace them with your own test data.

Base URL

PROD
https://api.boltutil.com