代收建单

POST /api/v1/collect/orders

创建一笔代收单，获取需提供给付款人的付款信息。

付款人必须转入“订单金额”payable_amount，而不是您提交的原始金额

ST Pay 会在原始金额上加上 0.01 至 0.99 的识别尾数，例如原始金额为 1000.00，订单金额可能是 1000.37。ST Pay 依据这个精确金额识别入账属于哪一笔订单。如果您使用 json 模式自行展示付款页面，请清晰显示订单金额，并提醒付款人按此金额转账。

订单在建单后 30 分钟失效（expires_at）。到期仍未入账的订单会被系统拒绝，并发送失败 Callback。
response_mode 决定返回内容：
- url：返回 ST Pay 付款页地址 payment_url，将付款人跳转到该页面即可。
- json：返回收款账号信息，由您自行展示付款页面。
同一会员最多同时有 10 笔待审批（pending）的代收单，超过时返回 user_active_orders_limit。

请求字段

字段	必填	格式	说明
`api_identity`	是	字符串	ST Pay 分配的 API 身份
`merchant_order_no`	是	1–200 个字符，字母、数字、`_`、`-`	您的订单号。在您的代收单中不能重复，无论原订单处于什么状态
`merchant_user_id`	二选一	1–200 个字符，字母、数字、`_`、`-`	付款会员在您系统中的唯一标识。传入时，以它判断是否为同一会员
`payer_name`	二选一	1–200 个字符，只能包含中文、英文字母、空格	付款人真实姓名。未传 `merchant_user_id` 时，以姓名判断是否为同一会员（不区分大小写，忽略所有空格）。不能包含数字或标点，例如 `Chan Tai-man` 中的连字符会被拒绝
`amount`	是	金额字符串	原始金额。单笔上下限以此金额判断（不含尾数）
`channel_type`	是	`fps` 或 `bank_transfer`	通道类型
`response_mode`	是	`url` 或 `json`	返回模式，说明见上方
`language`	否	`zh-TW`、`zh-CN` 或 `en`	付款页的语言：繁体中文、简体中文、英文。不传或空字符串为 `zh-TW`。只影响 `url` 模式的付款页
`callback_url`	是	网址，最多 500 个字符	该订单的 Callback 发往此地址，建单后不能更改。`http` 或 `https` 都可以，不能是本机或内网地址，见 Callback 地址
`timestamp`	是	`yyyy-MM-dd HH:mm:ss`	发送请求当下的时间（UTC+8），与 ST Pay 服务器时间相差超过 5 分钟会被拒绝，见请求与响应格式
`sign`	是	64 位小写十六进制	见签名

merchant_user_id 与 payer_name 至少传一个；空字符串或全是空格均视为未传。两个都未传时返回 missing_member_identity。两个都传时，以 merchant_user_id 判断会员，姓名仅用于展示。

请求示例

{
  "api_identity": "qp_Xk3vT9aLm2QwE7rB1nZc",
  "merchant_order_no": "MO20261013-0001",
  "merchant_user_id": "U10086",
  "payer_name": "王小明",
  "amount": "1000.00",
  "channel_type": "fps",
  "response_mode": "url",
  "callback_url": "https://shop.example.com/qpay/callback",
  "timestamp": "2026-10-13 10:00:00",
  "sign": "566fac06060d54d7450b41b6858b1ddf33df9d37117ab8a8c495ce748469f2b2"
}

响应字段

字段	返回条件	说明
`order_no`	始终返回	ST Pay 订单号
`merchant_order_no`	始终返回	您提交的商户单号
`status`	始终返回	固定为 `pending`
`payment_url`	`url` 模式	付款页地址，见付款页
`channel_type`	`json` 模式	`fps` 或 `bank_transfer`
`bank_name`	`json` 模式且为 `bank_transfer`	收款银行名称
`bank_code`	`json` 模式且为 `bank_transfer`	收款银行代码（字符串，保留开头的 0）
`account_no`	`json` 模式	完整收款账号
`account_name`	`json` 模式	收款户名
`payable_amount`	始终返回	订单金额，等于原始金额加识别尾数。付款人须转入此金额
`expires_at`	始终返回	失效时间，等于建单时间加 30 分钟
`sign`	始终返回	响应签名，以本次请求使用的密钥计算，见验证响应。验签通过才使用 `account_no`、`payment_url`

响应示例：url 模式

{
  "code": "OK",
  "message": "成功",
  "data": {
    "order_no": "C202610131000051230000",
    "merchant_order_no": "MO20261013-0001",
    "status": "pending",
    "payment_url": "https://pay.vincoterra.com/pay/QzIwMjYxMDEzMTAwMDA1MTIzMDAwMA.v3Kd9QeLr7Zp1sWm4XyT8bN2cF6hJ0aG5uE-iOkRtYw",
    "payable_amount": "1000.37",
    "expires_at": "2026-10-13 10:30:05",
    "sign": "7e876d9780d033c6224f52015eb15e1d1a9bbda9b75764fff0cdbf3d36b183ee"
  }
}

请求为 "merchant_order_no": "MO20261013-0002"、"payer_name": "Chan Tai Man"、"amount": "2000.00"、"channel_type": "bank_transfer"、"response_mode": "json"、"callback_url": "https://shop.example.com/qpay/callback"、"timestamp": "2026-10-13 10:01:17"，签名为 e20f45942090246543ab7bd95a1fecd52011699382a93637529c2aa987767848。

{
  "code": "OK",
  "message": "成功",
  "data": {
    "order_no": "C202610131001178820000",
    "merchant_order_no": "MO20261013-0002",
    "status": "pending",
    "channel_type": "bank_transfer",
    "bank_name": "The Hongkong and Shanghai Banking Corporation Limited",
    "bank_code": "004",
    "account_no": "123-456789-001",
    "account_name": "WONG KA YAN",
    "payable_amount": "2000.58",
    "expires_at": "2026-10-13 10:31:17",
    "sign": "4cd29b8f52d256516363af07eccfb821caaef52a10777cdc5495b809447aa175"
  }
}

json 模式且通道为 fps 时，不返回 bank_name 与 bank_code，account_no 为 FPS 收款账号。

付款页

使用 url 模式时：

页面显示订单金额、通道类型、收款账号与户名、失效时间；银行转账还会显示银行名称与代码。
订单金额、银行代码、收款账号与户名旁有“复制”键。
订单一旦结束（成功、拒绝、超时），页面只会显示“订单已结束”，不再显示收款信息。付款人停留在页面上时会自动切换到这个画面，无需刷新。
页面语言按建单时的 language 显示，付款人无法切换。
该地址本身就是访问凭证，持有该地址即可看到完整收款账号。请只提供给该笔订单的付款人，不要写入公开的日志、分析工具或分享链接。
请完整使用返回的地址，不要修改或自行拼接，任何改动都会导致页面显示“找不到頁面”（找不到订单时不知道建单语言，一律以繁体中文显示）。

可能的错误

invalid_signature、timestamp_expired、ip_not_allowed、merchant_disabled、missing_parameter、invalid_parameter、invalid_amount、missing_member_identity、invalid_callback_url、amount_out_of_range、merchant_order_no_duplicate、user_active_orders_limit、channel_full、no_available_card、internal_error。说明见错误码。