> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # 通过交易 Hash 查询订单 > 通过交易 Hash 查询对应的店铺订单，支持支付成功、少付和多付。一个交易可能包含多笔付款，`data` 按订单分组返回。 ## 认证与查询范围 使用对应店铺的 API Key，只能查询该店铺的订单。认证方式见[认证与签名](/zh/api/getting-started#认证与签名)。 GET 请求体必须为空，签名正文为 `{timestamp}.{nonce}.`，保留末尾的点，不拼接查询参数。每次请求使用新的 nonce 和有效时间戳，Secret Key 应保存在商户服务端。 ## 网络与 Hash 格式 | chain_type | 网络 | Hash 格式 | | --- | --- | --- | | 1 | TRON | 64 位十六进制，可带一个 0x/0X；返回小写、不带 0x | | 2 | Ethereum | 64 位十六进制，可带一个 0x/0X；返回小写、带 0x | | 3 | Solana | Base58 交易签名，64 至 88 字符，解码为 64 字节；保留大小写 | | 4 | BSC | 同 Ethereum | | 5 | Polygon | 同 Ethereum | | 6 | Arbitrum | 同 Ethereum | | 8 | Base | 同 Ethereum | `chain_type` 和 `tx_hash` 均为必填，各传一次。`tx_hash` 最长 128 字符，首尾空白会去除。请提供完整交易 Hash，不要填写钱包地址、订单号或区块浏览器 URL。Hash 中不能包含空格或重复的 0x 前缀，Solana 签名不能转成小写。不支持的网络、格式错误或多余参数返回 400。 ## 金额与订单状态 - `amount_total` / `currency`：原订单计价金额和币种。 - `target_amount_total` / `target_currency`：订单应付代币金额和币种。 - `amount_received_total` / `paid_currency`：订单累计实收金额和币种。 - `matched_payments`：本交易 Hash 对应的付款记录。 金额以最小货币单位的整数返回。USDT/USDC 使用两位小数，例如 `1200` 表示 `12.00`。请按 int64 精确处理，避免浮点精度损失。应付币种与实收币种可能不同，不要直接跨币种相减。 订单是否支付成功以 `payment_status` 为准，只有 `paid` 表示支付成功。`transfer_status` 表示金额状态，例如少付 `partially_paid`、足额 `paid` 和多付 `overpaid`。少付或多付的订单可能尚未支付成功或已经过期。订单累计实收也可能包含其他交易的付款，不能当作本 Hash 的付款金额。 ## 查询结果与重试 未查询到匹配订单时，返回 200 和 `data: []`。空结果不能作为付款失败的依据；付款后暂未查到订单时，可稍后重试，或向支持团队提供网络和交易 Hash。 | HTTP 状态码 | 说明 | 处理建议 | | --- | --- | --- | | 400 | 请求参数错误 | 检查网络、Hash 和查询参数 | | 401 | 认证或访问权限不符合要求 | 检查店铺 API Key、签名和时间戳 | | 429 | 请求过于频繁 | 按 `Retry-After` 指示重试 | | 503 | 服务暂时不可用 | 退避后使用新的 nonce 重试 | 建议以 [Webhook 通知](/zh/api/webhook-notifications) 获取订单更新，本接口用于核对和低频补查。接口只查询订单，不改变订单状态。请勿缓存响应。以下示例均为虚构数据。 ## OpenAPI ````yaml /zh/api/openapi.json get /api/v1/checkout/sessions/by-transaction openapi: 3.1.0 info: title: StablePay 支付 API version: '2026-03-31' summary: 支付会话和支付方式查询 API。 description: >- StablePay 支付 API 的 OpenAPI 规范。 说明： - 基础 URL：https://api.stablepay.co - 认证方式：Bearer API Key + `X-StablePay-Timestamp` + `X-StablePay-Nonce` + `X-StablePay-Signature` - 签名字符串：`{timestamp}.{nonce}.{requestBody}` - 签名算法：HMAC-SHA256，小写 hex - GET 请求的 `requestBody` 为空字符串。 servers: - url: https://api.stablepay.co description: 生产环境 security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: 支付会话 description: 创建、查询和取消支付会话。 - name: 支付方式 description: 查询支付方式。 paths: /api/v1/checkout/sessions/by-transaction: get: tags: - 支付会话 summary: 通过交易 Hash 查询订单 description: >- 通过交易 Hash 查询对应的店铺订单，支持支付成功、少付和多付。一个交易可能包含多笔付款，`data` 按订单分组返回。 ## 认证与查询范围 使用对应店铺的 API Key，只能查询该店铺的订单。认证方式见[认证与签名](/zh/api/getting-started#认证与签名)。 GET 请求体必须为空，签名正文为 `{timestamp}.{nonce}.`，保留末尾的点，不拼接查询参数。每次请求使用新的 nonce 和有效时间戳，Secret Key 应保存在商户服务端。 ## 网络与 Hash 格式 | chain_type | 网络 | Hash 格式 | | --- | --- | --- | | 1 | TRON | 64 位十六进制，可带一个 0x/0X；返回小写、不带 0x | | 2 | Ethereum | 64 位十六进制，可带一个 0x/0X；返回小写、带 0x | | 3 | Solana | Base58 交易签名，64 至 88 字符，解码为 64 字节；保留大小写 | | 4 | BSC | 同 Ethereum | | 5 | Polygon | 同 Ethereum | | 6 | Arbitrum | 同 Ethereum | | 8 | Base | 同 Ethereum | `chain_type` 和 `tx_hash` 均为必填，各传一次。`tx_hash` 最长 128 字符，首尾空白会去除。请提供完整交易 Hash，不要填写钱包地址、订单号或区块浏览器 URL。Hash 中不能包含空格或重复的 0x 前缀，Solana 签名不能转成小写。不支持的网络、格式错误或多余参数返回 400。 ## 金额与订单状态 - `amount_total` / `currency`：原订单计价金额和币种。 - `target_amount_total` / `target_currency`：订单应付代币金额和币种。 - `amount_received_total` / `paid_currency`：订单累计实收金额和币种。 - `matched_payments`：本交易 Hash 对应的付款记录。 金额以最小货币单位的整数返回。USDT/USDC 使用两位小数，例如 `1200` 表示 `12.00`。请按 int64 精确处理，避免浮点精度损失。应付币种与实收币种可能不同，不要直接跨币种相减。 订单是否支付成功以 `payment_status` 为准，只有 `paid` 表示支付成功。`transfer_status` 表示金额状态，例如少付 `partially_paid`、足额 `paid` 和多付 `overpaid`。少付或多付的订单可能尚未支付成功或已经过期。订单累计实收也可能包含其他交易的付款，不能当作本 Hash 的付款金额。 ## 查询结果与重试 未查询到匹配订单时，返回 200 和 `data: []`。空结果不能作为付款失败的依据；付款后暂未查到订单时，可稍后重试，或向支持团队提供网络和交易 Hash。 | HTTP 状态码 | 说明 | 处理建议 | | --- | --- | --- | | 400 | 请求参数错误 | 检查网络、Hash 和查询参数 | | 401 | 认证或访问权限不符合要求 | 检查店铺 API Key、签名和时间戳 | | 429 | 请求过于频繁 | 按 `Retry-After` 指示重试 | | 503 | 服务暂时不可用 | 退避后使用新的 nonce 重试 | 建议以 [Webhook 通知](/zh/api/webhook-notifications) 获取订单更新，本接口用于核对和低频补查。接口只查询订单，不改变订单状态。请勿缓存响应。以下示例均为虚构数据。 operationId: lookupPaymentSessionsByTransaction parameters: - name: chain_type in: query required: true description: 必须指定网络，支持的枚举及规范见上表。 schema: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 8 example: 4 - name: tx_hash in: query required: true description: 完整交易 Hash，允许去除首尾空白；不是钱包地址、订单号或浏览器 URL。 schema: type: string minLength: 1 maxLength: 128 example: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' responses: '200': description: 查询成功，空列表是正常结果。 headers: Cache-Control: description: 响应禁止缓存。 schema: type: string enum: - no-store content: application/json: schema: $ref: '#/components/schemas/TransactionLookupResponse' examples: paid: summary: 支付成功 value: chain_type: 4 tx_hash: >- 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa data: - id: example-session order_id: example-merchant-order payment_status: paid transfer_status: paid amount_total: 1200 currency: usd target_amount_total: 1200 target_currency: USDT paid_currency: USDT amount_received_total: 1200 matched_payments: - payment_id: example-payment paid_currency: USDT amount_received: 800 partially_paid: summary: 少付且订单已过期 value: chain_type: 4 tx_hash: >- 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa data: - id: example-session order_id: example-merchant-order payment_status: expired transfer_status: partially_paid amount_total: 1200 currency: usd target_amount_total: 1200 target_currency: USDT paid_currency: USDT amount_received_total: 800 matched_payments: - payment_id: example-payment paid_currency: USDT amount_received: 800 overpaid: summary: 多付 value: chain_type: 4 tx_hash: >- 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa data: - id: example-session order_id: example-merchant-order payment_status: paid transfer_status: overpaid amount_total: 1200 currency: usd target_amount_total: 1200 target_currency: USDT paid_currency: USDT amount_received_total: 1500 matched_payments: - payment_id: example-payment paid_currency: USDT amount_received: 1500 alternative_currency: summary: 应付与实收币种不同 value: chain_type: 4 tx_hash: >- 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa data: - id: example-session order_id: example-merchant-order payment_status: expired transfer_status: partially_paid amount_total: 1200 currency: usd target_amount_total: 1200 target_currency: USDT paid_currency: USDC amount_received_total: 800 matched_payments: - payment_id: example-payment paid_currency: USDC amount_received: 800 empty: summary: 未查到订单 value: chain_type: 4 tx_hash: >- 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa data: [] '400': description: 请求参数错误：网络、Hash、重复/额外参数或非空 GET 请求体。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 认证或访问权限不符合要求。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: 请求过于频繁，遵循 Retry-After 后重试。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Retry-After: description: 延后重试的秒数。 schema: type: integer minimum: 0 '503': description: 服务暂时不可用，请稍后重试。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: javascript label: Node.js source: >- import { createHmac, randomUUID } from 'node:crypto'; const timestamp = Math.floor(Date.now() / 1000).toString(); const nonce = randomUUID(); const signature = createHmac('sha256', process.env.STABLEPAY_SECRET_KEY) .update(`${timestamp}.${nonce}.`) .digest('hex'); const url = new URL('https://api.stablepay.co/api/v1/checkout/sessions/by-transaction'); url.searchParams.set('chain_type', '4'); url.searchParams.set('tx_hash', process.env.TRANSACTION_HASH); const response = await fetch(url, { method: 'GET', headers: { Authorization: `Bearer ${process.env.STABLEPAY_API_KEY}`, 'X-StablePay-Timestamp': timestamp, 'X-StablePay-Nonce': nonce, 'X-StablePay-Signature': signature, }, }); console.log(response.status, await response.json()); - lang: bash label: curl source: >- curl --get 'https://api.stablepay.co/api/v1/checkout/sessions/by-transaction' \ --data-urlencode 'chain_type=4' \ --data-urlencode "tx_hash=$TRANSACTION_HASH" \ --header "Authorization: Bearer $STABLEPAY_API_KEY" \ --header "X-StablePay-Timestamp: $TIMESTAMP" \ --header "X-StablePay-Nonce: $NONCE" \ --header "X-StablePay-Signature: $SIGNATURE" components: parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 schema: type: string example: a1b2c3d4e5f6... schemas: TransactionLookupResponse: type: object required: - chain_type - tx_hash - data properties: chain_type: type: integer description: 查询网络。 enum: - 1 - 2 - 3 - 4 - 5 - 6 - 8 tx_hash: type: string description: 规范化后的查询 Hash，Solana 保留原始大小写。 data: type: array description: 匹配的店铺订单列表，未查到时为 []。 items: $ref: '#/components/schemas/TransactionLookupOrder' additionalProperties: false ErrorResponse: type: object description: 错误响应。 properties: error: type: object properties: type: type: string description: 错误类型。 code: type: string description: 错误代码。 message: type: string description: 错误信息。 param: type: string description: 相关参数。 doc_url: type: string description: 错误文档链接。 decline_code: type: string description: 拒绝代码。 request_log_url: type: string description: 请求日志链接。 charge: type: string description: 相关支付 ID。 request_id: type: string description: 请求 ID。 timestamp: type: integer format: int64 description: 错误发生时间，Unix 秒。 TransactionLookupOrder: type: object required: - id - order_id - payment_status - transfer_status - amount_total - currency - target_amount_total - target_currency - paid_currency - amount_received_total - matched_payments properties: id: type: string description: StablePay 订单/支付会话 ID，可用于原有会话查询接口。 order_id: type: string description: 商户订单号。 payment_status: type: string description: 订单支付状态，paid 表示支付成功。 enum: - pending - processing - paid - failed - expired transfer_status: type: string description: 金额状态，例如少付、足额和多付；订单支付结果以 payment_status 为准。 enum: - pending - confirming - partially_paid - paid - overpaid amount_total: type: integer description: 原订单计价金额，使用 currency 的最小货币单位。 format: int64 minimum: 1 currency: type: string description: 原订单计价币种，沿用现有 API 的小写格式，例如 usd、eur。 example: usd target_amount_total: type: integer description: 应付代币金额，使用 target_currency 的最小货币单位。 format: int64 minimum: 1 target_currency: type: string description: 应付代币币种，可能与实际 paid_currency 不同。 enum: - USDT - USDC paid_currency: type: string description: 实际实收币种。 enum: - USDT - USDC amount_received_total: type: integer description: 订单累计实收，使用订单 paid_currency 的最小货币单位，不是本 Hash 的转账金额。 format: int64 minimum: 1 matched_payments: type: array description: 本交易 Hash 对应的付款记录，可能有多条。 minItems: 1 items: $ref: '#/components/schemas/TransactionLookupPayment' additionalProperties: false TransactionLookupPayment: type: object required: - payment_id - paid_currency - amount_received properties: payment_id: type: string description: 支付记录 ID，与订单或会话 ID 不同。 paid_currency: type: string description: 实际实收币种。 enum: - USDT - USDC amount_received: type: integer description: 本条付款实收，使用 paid_currency 的最小货币单位；USDT/USDC 为两位小数。 format: int64 minimum: 1 additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key，例如 `Bearer sk_live_xxx`。 stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.