代收建單

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