PAYMENTS / CHECKOUT

托管付款页

每笔支付订单都有一个派付托管的付款页 checkoutUrl。商户只需把付款人重定向过去：页面负责展示金额、地址与二维码、倒计时、选币、重新报价和留邮箱。

商户一般只需要跳转 checkoutUrl

下面的公开接口主要供派付自己的付款页使用。只有在你要自建付款页时才需要直接调用；无论哪种方式，到账结果都以回调或服务端查询为准。

付款页行为

地址：{checkoutBaseUrl}/checkout/{checkoutToken}；checkoutToken 是 48 位随机十六进制，作为访问凭证，不要公开传播。
未选币的订单（AWAITING_CURRENCY）先展示可选币种与估算金额，付款人选定后锁价、分配地址，开始付款窗口倒计时。
付款窗口到点、未收到款且订单未过期时，可重新报价：地址不变，按新汇率刷新金额。规则见付款窗口与重新报价。
付款人可留邮箱：订单有邮箱时，状态变为已支付（含过期后到账）、部分支付、已过期时各发一封通知邮件。

公开接口

以下接口无需 AppSign 签名，以 checkoutToken 作为访问凭证。三个写接口按 IP + token 每分钟 20 次限流。

GET/api/v1/payment/checkout/{checkoutToken}

查询付款页展示所需的订单信息。查询时会先按过期规则刷新订单状态。

路径参数

checkoutToken

string required

订单的随机访问凭证（48 位十六进制），即 checkoutUrl 最后一段。

请求示例

curl -X GET "https://api.pqpa.com/api/v1/payment/checkout/3f9c...e1"

响应（节选）

Response

200OK

{
  "code": 0,
  "data": {
    "appOrderNo": "INV202610231200001234",
    "fiatCurrency": "USD",
    "fiatAmount": 100.00,
    "payCurrency": null,
    "status": "AWAITING_CURRENCY",
    "merchantName": "Demo Shop",
    "source": "INVOICE",
    "title": "10 月服务费",
    "expireTime": 1792736100000,
    "expireTimeMillis": 1792736100000,
    "serverTimeMillis": 1792732500000,
    "selectableTokens": [
      { "chainTokenId": 50, "chainCode": "TRON", "chainName": "Tron", "tokenSymbol": "USDT", "tokenType": "TRC20", "estimatedPayAmount": 100.010001 }
    ],
    "paymentWindowExpireTimeMillis": null,
    "canRequote": false,
    "payerEmail": null
  },
  "msg": ""
}

data 字段说明

`appOrderNo` string required	商户业务单号。
`fiatCurrency / fiatAmount` string? / number? optional	法币币种 / 金额。
`payCurrency` string? optional	收款币种；未选币时为 null。
`chainCode / chainName` string? optional	公链 code / 名称。
`chainNamespace` string? optional	公链命名空间，如 EVM / TRON / BTC。
`evmChainId` integer? optional	EVM chainId；非 EVM 为 null。
`explorerUrl` string? optional	区块浏览器地址。
`chainTokenId / tokenSymbol` integer? / string? optional	代币 id / 符号。
`tokenType` string? optional	代币类型，如 NATIVE / ERC20 / TRC20。
`contractAddress` string? optional	合约地址；原生币为 null。
`tokenDecimals` integer? optional	代币小数位。
`payAmount` number? optional	应付金额。
`rateSnapshotId / rate / rateSource` — optional	汇率快照，字段含义同创建订单。
`rateExpireTime / rateExpireTimeMillis` integer? optional	锁价过期时间（毫秒）。
`ratePrecision / payPrecision / slippageBps` integer? optional	报价精度 / 支付币种精度 / 滑点 bps。
`paidAmount / overpaidAmount` number optional	已到账金额 / 多付金额。
`payAddress / memo` string? optional	收款地址 / Memo（Tag）。
`status` string required	订单状态。
`exceptionReason / handlingStatus` string? optional	异常原因 / 处理状态。
`txHash` string? optional	最近一次匹配交易哈希。
`expireTime / expireTimeMillis` integer optional	订单过期时间（毫秒）。
`merchantName` string? optional	商户名称（应用名称）。
`merchantLogo` string? optional	预留，当前恒为 null。
`source` string? optional	订单来源：API / INVOICE / PAYMENT_LINK。
`title / description` string? optional	发票 / 收款链接的标题与说明；API 订单为 null。
`serverTimeMillis` integer required	服务器当前时间戳（毫秒），用于校正倒计时。
`selectableTokens` array? optional	付款人可选币种，仅 AWAITING_CURRENCY 时返回。 `chainTokenId`integer 代币 id，选币时提交。 `chainCode / chainName`string 公链。 `tokenSymbol / tokenType`string 代币符号 / 类型。 `estimatedPayAmount`number 按当前实时汇率估算的应付币数（估算失败的币种不返回）。
`paymentWindowExpireTimeMillis` integer? optional	本次锁价付款窗口截止（毫秒）；非付款人选币订单为 null。
`canRequote` boolean required	是否可重新报价：订单为 PENDING + 窗口已过 + 未收到任何款 + 订单未过期。
`payerEmail` string? optional	付款人邮箱（脱敏，如 `a***@b.com`）。

POST/api/v1/payment/checkout/{checkoutToken}/select

付款人选择币种：按实时汇率锁价、分配独立收款地址，订单转 PENDING，开启付款窗口。只允许 AWAITING_CURRENCY 的订单。响应结构同上方 GET。

Body 参数

application/json

chainTokenId

integer required

代币 id，取自 selectableTokens。

请求示例

curl -X POST "https://api.pqpa.com/api/v1/payment/checkout/3f9c...e1/select" \
  -H "Content-Type: application/json" \
  -d '{"chainTokenId":50}'

POST/api/v1/payment/checkout/{checkoutToken}/requote

重新报价：仅 canRequote=true 时允许，收款地址不变，按新汇率更新应付金额，窗口重新计时。无 body，响应结构同 GET。

请求示例

curl -X POST "https://api.pqpa.com/api/v1/payment/checkout/3f9c...e1/requote"

POST/api/v1/payment/checkout/{checkoutToken}/email

付款人留邮箱：订单为 AWAITING_CURRENCY / PENDING / PARTIAL_PAID 时可设置或修改，终态拒绝。响应 data=true。

Body 参数

application/json

email

string required

付款人邮箱，需符合邮箱格式，最多 128 个字符。

请求示例

curl -X POST "https://api.pqpa.com/api/v1/payment/checkout/3f9c...e1/email" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com"}'

错误码

code	名称	说明
`1007004020`	`PAYMENT_ORDER_NOT_FOUND`	支付订单不存在或不属于当前应用。按单号查询、收银台 checkoutToken 无效时都返回此码。
`1007004031`	`PAYMENT_ORDER_SELECT_NOT_ALLOWED`	订单当前状态不能选择币种（只有「待选择币种」的订单可以选币）。
`1007004032`	`PAYMENT_ORDER_TOKEN_NOT_SELECTABLE`	该币种不在本订单可选范围内。
`1007004023`	`PAYMENT_ORDER_TOKEN_NOT_ENABLED`	应用未启用该支付代币（或应用没有任何已启用代币、payCurrency 匹配不到）。
`1007004022`	`PAYMENT_ORDER_RATE_NOT_SUPPORTED`	该法币 / 收款币种组合没有可用报价（未配置汇率且实时报价不可用）。
`1007004033`	`PAYMENT_ORDER_REQUOTE_NOT_ALLOWED`	当前不能重新报价：付款窗口未结束、已收到款项或订单已结束。
`1007004034`	`PAYMENT_ORDER_EMAIL_NOT_ALLOWED`	订单已结束，不能再修改邮箱。

触发限流时返回框架通用的限流错误码。