创建收款订单
创建收款订单，返回 pay_url 供付款人打开。有效期默认 10 分钟，可通过 expires_at 指定，最长 30 分钟。请求使用签名鉴权。
JSON 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
third_order_no | string | 是 | 三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019 |
payment_amount | string | 是 | 收款金额，USDT，正数；最多 24 位整数、2 位小数 |
expires_at | string | 否 | 过期时间，秒级 RFC 3339，须包含时区；须晚于当前时间且不超过 30 分钟。未传或空字符串默认 10 分钟 |
custom_params | string | 否 | 自定义参数，最多 500 字符；原样返回，默认空字符串 |
callback_url | string | 否 | 本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知 |
json
{
"third_order_no": "ORDER202610220001",
"payment_amount": "10.00",
"expires_at": "2026-10-22T00:20:00Z",
"custom_params": "customer=example",
"callback_url": "https://merchant.example.com/notify/payment"
}成功响应
json
{
"request_id": "7d5f6832c7494cb28e413f97f8460981",
"code": 0,
"message": "成功",
"data": {
"pay_url": "https://t.me/example_bot?start=pay_202610220000000042",
"expires_at": "2026-10-22T00:20:00Z",
"order_id": "202610220000000042",
"app_id": "1234567890",
"third_order_no": "ORDER202610220001",
"currency": "USDT",
"payment_amount": "10.00",
"fee_amount": "0.63",
"fee_rate": "636",
"actual_amount": "9.37",
"status": "PENDING",
"refund_status": "NONE",
"custom_params": "customer=example",
"callback_url": "https://merchant.example.com/notify/payment",
"create_time": "2026-10-22T00:00:00Z",
"close_time": "",
"pay_time": "",
"update_time": "2026-10-22T00:00:00Z"
}
}| 字段 | 类型 | 说明 |
|---|---|---|
data.pay_url | string | Telegram 付款链接，打开后由付款人确认支付 |
data.expires_at | string | 订单到期时间，RFC 3339 / UTC |
data.callback_url | string | 本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知 |
data.order_id | string | 平台订单ID，YYYYMMDD + 10位随机数字，表内唯一 |
data.app_id | string | 商户 APPID，由鉴权请求头确定 |
data.third_order_no | string | 三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019 |
data.currency | string | 币种，固定为 USDT |
data.payment_amount | string | 收款金额，USDT，正数；最多 24 位整数、2 位小数 |
data.fee_amount | string | 手续费 = 收款金额 × 费率基点 ÷ 10000；截断至 2 位小数，不四舍五入 |
data.fee_rate | string | 订单费率，基点整数 0–10000；636 表示 6.36% |
data.actual_amount | string | 收款金额 − 手续费；待支付时为预计到账金额 |
data.status | string | 订单状态：PENDING 待支付，TIMEOUT 已超时，PAID 已支付，CLOSED 已关闭 |
data.refund_status | string | 退款状态：NONE 无退款，PARTIAL 部分退款，FULL 全额退款 |
data.custom_params | string | 自定义参数，最多 500 字符；原样返回，默认空字符串 |
data.create_time | string | 创建时间，RFC 3339 格式，UTC 时区 |
data.close_time | string | 关闭时间，RFC 3339 / UTC；未关闭时为空字符串 |
data.pay_time | string | 付款时间，RFC 3339 / UTC；未支付时为空字符串 |
data.update_time | string | 更新时间，RFC 3339 格式，UTC 时区 |
公共响应字段见通用约定。
业务错误
| code | message | 处理方式 |
|---|---|---|
| 1018 | 收款金额格式不正确 | payment_amount 必须是大于 0 的十进制字符串，最多 24 位整数、2 位小数；不接受科学计数法。 |
| 1019 | 订单号已存在 | 同一 APPID 下三方订单号不可重复；请查询原订单或使用新的订单号创建。 |
| 1027 | 回调地址格式不正确 | callback_url 可不传或为空字符串；填写时须为有效 HTTPS 地址，最多 2048 字节，不允许账号密码、片段或空白字符。 |
| 1033 | 收款机器人暂不可用 | 联系服务方核实收款机器人状态后重试。 |
| 1034 | 收款订单过期时间不正确 | expires_at 须为秒级 RFC 3339 时间，晚于当前时间且不超过 30 分钟；未传或空字符串默认 10 分钟。 |
填写 callback_url 后，订单结果按结果通知发送；未填写则不通知。