代付建單

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。說明見錯誤碼。

代付建單

請求欄位

收款帳號格式

請求範例

回應欄位

可能的錯誤