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"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());{
"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
}
]
}
]
}通过交易 Hash 查询订单
通过交易 Hash 查询当前 API Key 所属商户和店铺已明确关联的链上付款与订单。支持支付成功、少付和多付。一个 Hash 可能包含多笔付款，data 按订单分组返回列表。
认证和查询范围
使用已绑定店铺的商户 API Key，沿用 Bearer API Key 和三个签名请求头。身份仅由 API Key 决定，不能传入 merchant_id、store_id 或自定义身份头扩大范围。无店铺绑定的 Key 无法调用此接口。详见认证与签名。
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 通知 为主，本接口用于核对和低频补查，不触发补单、入账或退款。示例均为虚构数据；Node.js 示例计算完整签名，curl 示例需要预先准备签名请求头。
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"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());{
"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
}
]
}
]
}授权
Bearer API Key，例如 Bearer sk_live_xxx。
Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。
使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。
请求头
Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。
16 - 64使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。
查询参数
必须指定网络，支持的枚举及规范见上表。
1, 2, 3, 4, 5, 6, 8 完整交易 Hash，允许去除首尾空白；不是钱包地址、订单号或浏览器 URL。
1 - 128此页面对您有帮助吗？