> ## 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 查询当前 API Key 所属商户和店铺已明确关联的链上付款与订单。支持支付成功、少付和多付。一个 Hash 可能包含多笔付款，`data` 按订单分组返回列表。 ## 认证和查询范围 使用已绑定店铺的商户 API Key，沿用 Bearer API Key 和三个签名请求头。身份仅由 API Key 决定，不能传入 `merchant_id`、`store_id` 或自定义身份头扩大范围。无店铺绑定的 Key 无法调用此接口。详见[认证与签名](/zh/api/getting-started#认证与签名)。 GET 请求体必须为空，签名正文为 `{timestamp}.{nonce}.`，保留末尾的点，不拼接查询参数。每次重试使用新 nonce 和有效时间戳，密钥保存在商户服务端。两个查询参数各传一次，不接受额外参数、数组或重复参数。 ## 网络与 Hash 规范 | chain_type | 网络 | 输入与规范化 | | --- | --- | --- | | 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 | 必须指定网络，不能根据 Hash 自动推断；未列出的网络返回 400。`tx_hash` 最长 128 字符，首尾空白会去除。内部空格、重复前缀、非法字符、错误长度或区块浏览器完整 URL 返回 400。Solana 签名不能转成小写。生产和测试入口分别查询各自环境。 ## 金额与支付状态 `amount_total/currency` 为原订单计价金额；`target_amount_total/target_currency` 为应付代币金额；`amount_received_total/paid_currency` 为订单累计实收；`matched_payments` 仅包含本 Hash 的有效付款。不要将累计实收当作本 Hash 的付款金额。 金额为业务最小单位整数，USDT/USDC 使用两位小数，1200 表示 12.00，不是链上 6/18 位精度的 raw amount。按 int64 精确处理，避免浮点精度损失。应付 USDT、实际已识别 USDC 的少付订单会分别返回应付与实收币种，不跨币种直接相减。 `payment_status` 保留真实订单状态。少付、多付订单可能为 pending、processing、failed 或 expired，查询命中不代表订单支付成功；仅 paid 表示订单支付成功。少付也可能已被商户既有容差策略接受。`transfer_status` 是金额分类，两种状态应分别读取。 ## 空结果、错误和重试 没有匹配、尚未完成识别、没有可公开的关联、属于其他商户或店铺，均返回 200 和 `data: []`。接口不返回候选订单、异常收款详情或其他租户的信息。只有已完成且金额、币种、订单归属明确的付款才会返回。空结果不能证明链上没有付款、资金丢失或商户结算已完成；历史不完整记录也可能无法查到。 参数错误返回 400，认证或店铺绑定不满足要求返回 401，限流返回 429，查询不可用返回 503。单次最多处理 100 条匹配的支付记录，超过时返回 503，不会静默截断。真实查询失败不会伪装成空列表。429 遵循 Retry-After，503 退避后使用新 nonce 重试。 响应禁止缓存。建议以 [Webhook 通知](/zh/api/webhook-notifications) 为主，本接口用于核对和低频补查，不触发补单、入账或退款。示例均为虚构数据；Node.js 示例计算完整签名，curl 示例需要预先准备签名请求头。 ## 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 查询当前 API Key 所属商户和店铺已明确关联的链上付款与订单。支持支付成功、少付和多付。一个 Hash 可能包含多笔付款，`data` 按订单分组返回列表。 ## 认证和查询范围 使用已绑定店铺的商户 API Key，沿用 Bearer API Key 和三个签名请求头。身份仅由 API Key 决定，不能传入 `merchant_id`、`store_id` 或自定义身份头扩大范围。无店铺绑定的 Key 无法调用此接口。详见[认证与签名](/zh/api/getting-started#认证与签名)。 GET 请求体必须为空，签名正文为 `{timestamp}.{nonce}.`，保留末尾的点，不拼接查询参数。每次重试使用新 nonce 和有效时间戳，密钥保存在商户服务端。两个查询参数各传一次，不接受额外参数、数组或重复参数。 ## 网络与 Hash 规范 | chain_type | 网络 | 输入与规范化 | | --- | --- | --- | | 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 | 必须指定网络，不能根据 Hash 自动推断；未列出的网络返回 400。`tx_hash` 最长 128 字符，首尾空白会去除。内部空格、重复前缀、非法字符、错误长度或区块浏览器完整 URL 返回 400。Solana 签名不能转成小写。生产和测试入口分别查询各自环境。 ## 金额与支付状态 `amount_total/currency` 为原订单计价金额；`target_amount_total/target_currency` 为应付代币金额；`amount_received_total/paid_currency` 为订单累计实收；`matched_payments` 仅包含本 Hash 的有效付款。不要将累计实收当作本 Hash 的付款金额。 金额为业务最小单位整数，USDT/USDC 使用两位小数，1200 表示 12.00，不是链上 6/18 位精度的 raw amount。按 int64 精确处理，避免浮点精度损失。应付 USDT、实际已识别 USDC 的少付订单会分别返回应付与实收币种，不跨币种直接相减。 `payment_status` 保留真实订单状态。少付、多付订单可能为 pending、processing、failed 或 expired，查询命中不代表订单支付成功；仅 paid 表示订单支付成功。少付也可能已被商户既有容差策略接受。`transfer_status` 是金额分类，两种状态应分别读取。 ## 空结果、错误和重试 没有匹配、尚未完成识别、没有可公开的关联、属于其他商户或店铺，均返回 200 和 `data: []`。接口不返回候选订单、异常收款详情或其他租户的信息。只有已完成且金额、币种、订单归属明确的付款才会返回。空结果不能证明链上没有付款、资金丢失或商户结算已完成；历史不完整记录也可能无法查到。 参数错误返回 400，认证或店铺绑定不满足要求返回 401，限流返回 429，查询不可用返回 503。单次最多处理 100 条匹配的支付记录，超过时返回 503，不会静默截断。真实查询失败不会伪装成空列表。429 遵循 Retry-After，503 退避后使用新 nonce 重试。 响应禁止缓存。建议以 [Webhook 通知](/zh/api/webhook-notifications) 为主，本接口用于核对和低频补查，不触发补单、入账或退款。示例均为虚构数据；Node.js 示例计算完整签名，curl 示例需要预先准备签名请求头。 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: 支付成功，本 Hash 实收与订单累计实收不同 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: 应付 USDT、实收 USDC 的明确少付订单 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: 查询暂不可用或超过 100 条支付记录的处理上限，不代表未付款。 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: 当前商户和店铺可见的订单，没有匹配时为 []。 maxItems: 100 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: 真实订单状态，查询匹配成功不会改变订单状态。 enum: - pending - processing - paid - failed - expired transfer_status: type: string description: 金额分类。pending/confirming 表示金额分类尚未完成；不能单凭此字段推断本笔付款是否识别。 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 maxItems: 100 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.