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
        }
      ]
    }
  ]
}

支付 API

通过交易 Hash 查询订单

通过交易 Hash 查询对应的店铺订单，支持支付成功、少付和多付。一个交易可能包含多笔付款，data 按订单分组返回。

认证与查询范围

使用对应店铺的 API Key，只能查询该店铺的订单。认证方式见认证与签名。

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 通知获取订单更新，本接口用于核对和低频补查。接口只查询订单，不改变订单状态。请勿缓存响应。以下示例均为虚构数据。

GET

api

checkout

sessions

by-transaction

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
        }
      ]
    }
  ]
}

授权

Authorization

string

header

必填

Bearer API Key，例如 Bearer sk_live_xxx。

X-StablePay-Timestamp

string

header

必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce

string

header

必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

X-StablePay-Signature

string

header

必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

请求头

X-StablePay-Timestamp

string

必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce

string

必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

Required string length: 16 - 64

X-StablePay-Signature

string

必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

查询参数

chain_type

enum<integer>

必填

必须指定网络，支持的枚举及规范见上表。

可用选项:

1,

2,

3,

4,

5,

6,

8

tx_hash

string

必填

完整交易 Hash，允许去除首尾空白；不是钱包地址、订单号或浏览器 URL。

Required string length: 1 - 128

响应

查询成功，空列表是正常结果。

chain_type

enum<integer>

必填

查询网络。

可用选项:

1,

2,

3,

4,

5,

6,

8

tx_hash

string

必填

规范化后的查询 Hash，Solana 保留原始大小写。

data

object[]

必填

匹配的店铺订单列表，未查到时为 []。

Show child attributes

开始使用

支付 API

二维码支付 API

全球账户 API

稳定币兑换 API

退款 API

订阅 API

发票 API

账单 API

付款 API

通过交易 Hash 查询订单

认证与查询范围

网络与 Hash 格式

金额与订单状态

查询结果与重试

授权

请求头

查询参数

响应