查询付款结果与订单状态

POST /api/v1/order/status

请求鉴权

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

01. 请求参数

application/json

externalOrderId必填

String

传入创建订单时使用的商户订单号 externalOrderId。不要传 orderToken；查询范围限于当前 API Key 所属商户。

填写示例

{"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。

paymentRouteString / null

实际付款通道：DIRECT 为直接转账，SPLIT 为分账付款。尚未结算的查询结果可能为 null；不代表付款已确认。

platformFeeString / null

本次实际平台费，币种与 currency 相同，以字符串返回；查询尚未记录时可能为 null。直付或免平台费付款为 0，不含网络费。

merchantNetAmountString / null

商户净收款，币种与 currency 相同，以字符串返回。分账时为付款总额减平台费；查询尚未记录时可能为 null，历史回调可回退为实付金额。

manuallyAcceptedBoolean

当前仅 settlementType 为 MANUAL_UNDERPAID 时返回 true；不代表所有人工处理。请用 settlementType 判断具体类型。

externalOrderIdString

创建订单时传入的商户订单号，用于查询和关联您的业务订单。

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 对象，不参与付款匹配。

查询注意事项

查询返回系统当前保存的订单状态，不会因本次查询立即扫描链上交易。确认数仅为已记录值，请以订单状态判断是否已确认。
尚无匹配付款时，paidAmount、shortfallAmount、settlementType、txHash 和相关时间可能为 null；这不代表查询失败。
只能查询当前商户的订单。免费商户可查询最近 30 天创建的订单，会员可查询全部历史订单；不存在或超出可见范围时返回订单不存在。
paidAt、confirmedAt 和 completedAt 是日期时间字符串，如 2026-02-09T18:20:50.790，当前不带时区偏移；不是毫秒时间戳。

常见错误

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

401：检查 API Key、原始正文签名以及当前毫秒时间戳；与服务器时间差不能超过 5 分钟。
404：订单不存在，或不属于当前商户、超出当前套餐可查询范围。