开发文档

创建稳定币支付订单

从商户服务端签名创建 USDT / USDC 支付订单。查看必填参数、收款网络、完整应付金额、收银台链接、订单有效期与回调配置，保存商户订单号后展示付款信息。

POST /api/v1/order/create

请求鉴权

请求必须包含 X-Bolt-Key、X-Bolt-Timestamp 和 X-Bolt-Signature。请使用当前毫秒时间戳，并对时间戳与请求体原文生成签名。

USDTUSDC

精确金额匹配

为什么接口返回的支付金额可能会多一点

入门方案

3 位固定

专业方案

2-6 位可调

系统会按金额识别精度向上取整；同一网络、币种和收款钱包下，如有待支付订单使用相同金额，会再增加小额差值以区分订单。返回的应付金额不会低于提交的原始金额。免费版固定使用 3 位识别精度，会员可选择 2–6 位。请以接口返回的 payment.amount 为准。

匹配流程

创建订单

1

amount

后端提交原始结算金额，BoltUtil 返回链上应付金额。

展示收银台

2

payment.amount

前端展示返回的精确金额、网络和收款地址。

链上对账

3

Webhook

监听器按网络、地址、Token、金额和状态完成通知。

接入注意事项

1

请展示创建订单响应中的 payment.amount，而不是请求中的 amount 或原始商品价格。

2

不要四舍五入、截断或移除这部分很小的小数偏移。

3

修改偏移位只影响新创建订单，不会重算已有待支付订单。

4

收到 Webhook 后，先验证签名并处理重复通知，再根据 externalOrderId 和已确认的付款状态完成交付；待确认付款不代表支付成功。

01. 请求参数

JSON Payload
amount
必填
Decimal

商品或业务订单的原始金额，单位为 currency 指定的币种。建议以字符串传入，避免浮点精度损失。付款方应支付响应中的 payment.amount，而非直接使用此值。

基础最小金额：1.00；还须满足所选网络与币种配置的最低支付金额。精度限制: 最大 6 位小数⚠️ 安全风险: 严禁透传由前端计算的金额。请务必在后端通过数据库价格计算，防止篡改。
externalOrderId
必填
String

您的业务系统订单 ID，用于关联 BoltUtil 订单。订单查询使用 externalOrderId；创建响应以 merchantExternalId 返回，Webhook 以 externalOrderId 返回。

商户维度全局唯一支持：字母、数字、下划线 (_)、连字符 (-)长度限制：6 - 64 字符重复提交相同订单号会报错，不会返回已有订单。
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必须公网可访问锁定机制：一旦生成订单，该地址将不可变更，请务必在下单前确认可用性。⚠️ 创建订单前，必须在商户后台配置并启用 Webhook 和签名密钥；传入此参数不能替代该配置。长度限制：最多 255 字符
returnUrl
URL

支付完成或用户主动返回时，收银台会将浏览器跳转至此 URL。该地址仅用于页面跳转，不代表支付结果。

支付结果请以签名 Webhook 或订单状态查询为准未传入时，默认返回 https://boltutil.com。长度限制：最多 255 字符
expiredMinutes
Long

订单从创建起保持可支付状态的分钟数。免费版固定为 30 分钟，专业版会员可在 15-60 分钟范围内设置。

可设置范围: 15-60 分钟默认值: 30 分钟仅专业版会员可自定义；免费版固定为 30 分钟免费版忽略合法范围内的自定义值，统一按 30 分钟创建；实际到期时间以 time.expireTimestamp 为准。
metadata
Map

商户自定义的 JSON 数据。BoltUtil 不修改其内容，并会在创建订单响应、订单查询结果及 Webhook 回调中原样返回。

格式: 标准 JSON 对象内容原样透传，不参与支付匹配最多 10 个顶层键

02. 响应字段

application/json
orderToken
BoltUtil 订单标识，用于访问收银台。商户 API 查询订单时请使用 externalOrderId。
merchantExternalId
对应请求参数中的 externalOrderId。
status
创建成功时为 PENDING（待支付）。后续付款及回调状态请见查询订单文档。
查询订单状态 →
checkoutUrl
专属收银台支付链接。
returnUrl
收银台返回地址。未传入时默认为 https://boltutil.com。
metadata
商户自定义透传数据对象。

data.payment { ... }

address
该订单使用的商户收款钱包地址。同一钱包可用于多个订单，并非每单生成新地址。
amount
付款方应支付的准确金额，以字符串返回。请完整展示，不要四舍五入或截断。
rawAmount
以最小单位表示的整数金额，以字符串返回。换算方式：payment.amount × 10^payment.decimal。例如 decimal 为 6 时，1 个币种单位对应 1,000,000 个最小单位。
currency
币种符号。
network
网络标识。
qrData
用于生成收款二维码的地址字符串，不含金额、币种或网络。请另行展示 payment.amount、currency 和 network。
decimal
该网络上所选币种的链上精度，用于换算 rawAmount；不是订单金额识别精度。

data.time { ... }

expireTimestamp
位于 data.time，表示订单到期时间，单位为毫秒（Unix 时间戳）。
serverTimestamp
位于 data.time，表示生成响应时的服务器时间，单位为毫秒（Unix 时间戳）。

常见错误

以下为常见情况，实际以 HTTP 状态码和响应中的 code、message 为准。错误响应不是付款结果；请求失败时请先定位原因。

  • 401：检查 API Key、原始正文签名以及当前毫秒时间戳；与服务器时间差不能超过 5 分钟。
  • 400：externalOrderId 已存在。请查询原订单状态，避免把同一业务重复创建为新订单。
  • 400：检查必填参数、网络与币种是否可用、收款钱包以及已启用的 Webhook 配置。
  • 429：请求触发频率限制，或当前免费套餐的每日订单创建额度已用尽。请结合业务错误码与 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"

地址、交易哈希及订单均为示例。请替换为您自己的测试数据。

Base URL

PROD
https://api.boltutil.com