代付建单

POST /api/v1/payout/orders

创建一笔代付单，由 ST Pay 从您的余额向指定收款人付款。

建单时会检查可用余额 ≥ 代付金额 + 手续费，不足时返回 insufficient_balance，不会建单。
建单不会冻结或预留余额。ST Pay 实际出款时才扣款，并会再次检查余额。若您同时创建多笔代付单，合计金额可能超过余额；出款时余额不足的订单会保持待审批状态，并可能被拒绝。
手续费率在建单时锁定，之后的费率调整不影响该订单。建单响应不包含手续费，出款后可通过 Callback 或查单获取。

请求字段

字段	必填	格式	说明
`api_identity`	是	字符串	ST Pay 分配的 API 身份
`merchant_order_no`	是	1–200 个字符，字母、数字、`_`、`-`	您的订单号。在您的代付单中不能重复，代收与代付分别独立计算
`amount`	是	金额字符串	代付金额，也是手续费的计算基数
`channel_type`	是	`fps` 或 `bank_transfer`	通道类型
`account_no`	是	因通道而异，见收款账号格式	收款账号
`account_name`	是	1–200 个字符	收款人姓名或户名
`bank_name`	银行转账必填	1–100 个字符	收款银行名称。FPS 不可传
`bank_code`	银行转账必填	字符串	收款银行代码，须为银行代码列表中的值，保留开头的 0。FPS 不可传
`callback_url`	是	网址，最多 500 个字符	该订单的 Callback 发往此地址，建单后不能更改。`http` 或 `https` 都可以，不能是本机或内网地址，见 Callback 地址
`timestamp`	是	`yyyy-MM-dd HH:mm:ss`	发送请求当下的时间（UTC+8），与 ST Pay 服务器时间相差超过 5 分钟会被拒绝，见请求与响应格式
`sign`	是	64 位小写十六进制	见签名

收款账号格式

通道	`account_no` 支持的格式
`fps`	以下三种任选其一，填在同一个字段中：・手机号码：8 位数字，例如 `91234567` ・Email：最长 200 个字符，只能包含字母、数字与 `@ . _ -`；恰好一个 `@` 且前后都有字符，`@` 后面要有 `.`，例如 `chan.taiman@example.com` ・FPS 识别码：1 至 50 位数字
`bank_transfer`	数字与连字符 `-`，1 至 50 个字符，例如 `012-345678-001`

FPS 订单传了 bank_name 或 bank_code 会返回 invalid_parameter；银行转账订单缺少其中任何一个会返回 missing_parameter。

请求示例

FPS

{
  "api_identity": "qp_Xk3vT9aLm2QwE7rB1nZc",
  "merchant_order_no": "PO20261013-0001",
  "amount": "500.00",
  "channel_type": "fps",
  "account_no": "91234567",
  "account_name": "陳大文",
  "callback_url": "https://shop.example.com/qpay/callback",
  "timestamp": "2026-10-13 10:05:22",
  "sign": "693c80aaf437abcd6dbf60f8aed9e4eda09deed052977fa63cb9b1768150044f"
}

银行转账

{
  "api_identity": "qp_Xk3vT9aLm2QwE7rB1nZc",
  "merchant_order_no": "PO20261013-0002",
  "amount": "3000.00",
  "channel_type": "bank_transfer",
  "account_no": "012-345678-001",
  "account_name": "CHAN TAI MAN",
  "bank_name": "Bank of China (Hong Kong) Limited",
  "bank_code": "012",
  "callback_url": "https://shop.example.com/qpay/callback",
  "timestamp": "2026-10-13 10:06:40",
  "sign": "44aadf0a2be821c13c1aef71d8cc7cfc6cf012d3b15f543d2650cdf762002a2b"
}

响应字段

字段	说明
`order_no`	ST Pay 订单号
`merchant_order_no`	您提交的商户单号
`status`	固定为 `pending`
`amount`	代付金额
`sign`	响应签名，以本次请求使用的密钥计算，见验证响应

{
  "code": "OK",
  "message": "成功",
  "data": {
    "order_no": "P202610131005224410000",
    "merchant_order_no": "PO20261013-0001",
    "status": "pending",
    "amount": "500.00",
    "sign": "e2fe8e5d430ba4bf8a1003b0d7fc8eabcc5d7d974ceda5135783d1aecfa44c8a"
  }
}

invalid_signature、timestamp_expired、ip_not_allowed、merchant_disabled、missing_parameter、invalid_parameter、invalid_amount、invalid_callback_url、amount_out_of_range、merchant_order_no_duplicate、insufficient_balance、internal_error。说明见错误码。

代付建单

请求字段

收款账号格式

请求示例

响应字段

可能的错误