Callback 通知

訂單有結果時，ST Pay 會 POST 到該單建單時帶的 callback_url。

什麼時候發送

事件status是否發送
代收成功success發送
代收被拒絕（ST Pay 人工拒絕，或 30 分鐘到期被系統拒絕）rejected發送
代收逾時入帳late_credited不發送，請用查單確認，見訂單狀態
代付已出款paid發送
代付被拒絕rejected發送

Callback 網址

  • 每次建單（代收、代付）時以 callback_url 帶入，不需要事先提供給 ST Pay。每張單可以不同，例如測試與正式環境各用自己的網址。
  • 建單後不能更改。自動發送與 ST Pay 手動重發都送往該單建單時的網址。若您之後更換網址，舊單的通知仍送往舊網址；舊網址收不到時，請以查單確認舊單的結果。
  • 最多 500 字元，照原樣保存，不做任何轉換。
  • http 與 https 都可以，建議用 https：http 會以明文傳送訂單號與金額。不論哪一種，都務必驗證 sign，才能防止偽造或竄改的通知。
  • 使用 https 時，網站的 HTTPS 憑證（SSL/TLS 憑證）必須由公開的憑證機構簽發、在有效期限內、名稱與網址上的主機名稱相符，而且伺服器要送出完整的憑證鏈（含中繼憑證）。自簽憑證、過期、名稱不符或缺少中繼憑證都視為送達失敗，不會重試。
  • 不能含帳號密碼（user:pass@）、#、空白或非 ASCII 字元；中文網域請轉成 punycode（xn-- 開頭）。可以有 path 與 query。
  • 主機名稱只能有英數字、.、-（不能有底線 _），或以 [ ] 包住的 IPv6；有寫埠號時須為 1 至 65535（不能只寫 :）。
  • path 與 query 裡不能直接出現 |、{、}、^、"、<、>、\、反引號，% 後面必須是兩位十六進位數字；這些字元請先做 URL 編碼（例如 % 寫成 %25）。
  • 沒送、空字串或全是空白回 missing_parameter。
  • 不能是本機或內網位址，測試與正式環境都一樣：
    • localhost，以及 .localhost、.local、.localdomain、.internal、.intranet、.lan、.corp、.home.arpa、.private 結尾的網域，或不含「.」的主機名稱。
    • 私有、迴圈、鏈路本地、CGNAT、保留與文件用途、多播的 IP，例如 10.x.x.x、172.16.x.x–172.31.x.x、192.168.x.x、127.x.x.x、169.254.x.x、100.64.x.x；IPv6 只接受全球單播位址（2000::/3），其中 Teredo 2001::/32、文件用途 2001:db8::/32、6to4 2002::/16 也不接受。
    • 純數字、十六進位、八進位或省略段數的 IP 寫法，例如 2130706433、0x7f.0.0.1、0177.0.0.1、127.1。
    • 公網 IP 可以直接寫。
  • 不符合以上規則時，建單回 invalid_callback_url（格式錯誤、超過 500 字元則回 invalid_parameter），不會建單。
  • ST Pay 每次發送前（包括手動重發）會重新解析網域；解析失敗，或解析出的任何一個位址不是公網位址，這次就不發送，視為送達失敗。請確認網域可從公網解析，而且只指向公網 IP。

請求格式

  • 方法 POST，Content-Type: application/json，本文是 JSON 物件，所有值都是字串。
  • 包含 sign，簽章規則與 API 請求相同，使用您的 API 驗證金鑰（見更換金鑰）。Callback 不含 api_identity 與 timestamp。
  • ST Pay 等待連線最多 5 秒、等待回應最多 10 秒，且不跟隨重新導向（3xx）：收到 3xx 視為送達失敗。請直接填最終網址，例如 http 轉 https、少了結尾的 / 都可能造成轉址。
  • Callback 內容不含 callback_url。
  • 請求標頭固定帶 User-Agent: QPay-Callback/1.0 與 Accept: */*。Callback 網址在 Cloudflare、WAF 或其他防火牆後面時，請放行這個 User-Agent 與 POST 請求，否則可能被擋成 403 而送達失敗。

您必須回應的內容

回應 HTTP 2xx，且回應本文是純文字 ok（前後空白會被忽略）。其他任何回應，包括逾時、非 2xx、本文不是 ok，都視為送達失敗。

HTTP/1.1 200 OK
Content-Type: text/plain

ok

Callback 不會自動重試

每張單只會自動發送一次。送達失敗時，只有 ST Pay 人員能手動重發，重發一律送往該單建單時帶的 callback_url。因此：

  • 請不要只依賴 Callback。對於長時間沒有結果的訂單，請定期查單確認。
  • 同一張單可能收到不只一次 Callback（手動重發），請以 order_no 加 status 做冪等處理，已處理過的通知直接回 ok。
  • Callback 送達失敗不影響交易結果，訂單狀態與餘額不會因此回復。

欄位

欄位代收成功代收拒絕代付已出款代付拒絕說明
order_no✓✓✓✓ST Pay 訂單號
merchant_order_no✓✓✓✓商戶單號
statussuccessrejectedpaidrejected訂單狀態
received_amount✓實收金額
fee✓✓手續費
settlement_amount✓結算金額
payable_amount✓訂單金額（含尾數）
amount✓✓代付金額
finished_at✓✓✓✓完成時間
sign✓✓✓✓簽章

Callback 不帶拒絕原因，需要時請用查單取得。

代收與代付若帶同一個 callback_url，兩者的 status 都可能是 rejected，而且代收單與代付單的商戶單號可以相同。請以建單時取得的 order_no 對應訂單；如果要用商戶單號對應，請讓代收與代付使用不會重複的單號，例如加上不同前綴。

處理建議

  1. 解析 JSON，用收到的全部欄位（sign 以外）重新計算簽章並比對。不要只挑本文件列出的欄位，日後可能新增欄位。
  2. 簽章不符就丟棄，不要更新訂單。
  3. 以 order_no 找到您的訂單；已處理過相同結果時直接回 ok。
  4. 更新訂單後回 ok。耗時的後續處理（出貨、通知會員等）請放到背景執行，避免超過 10 秒。
  5. 代收成功請以 received_amount（實收金額，或扣除手續費後的 settlement_amount）入帳，不要用建單時的金額。實收金額與您預期的金額不同時，請轉人工確認，不要自動入帳。
  6. 訂單已是終態（success、paid、rejected）後，又收到較晚到、狀態不同的通知時，不要回退訂單狀態；請記錄下來轉人工，有疑義以查單結果為準。

範例

以下簽章都是以範例金鑰計算的實際值。

代收成功
{
  "order_no": "C202610131000051230000",
  "merchant_order_no": "MO20261013-0001",
  "status": "success",
  "received_amount": "1000.37",
  "fee": "25.00",
  "settlement_amount": "975.37",
  "finished_at": "2026-10-13 10:12:30",
  "sign": "49d9d35c3b3a97a55fe60976a331d36913b0d3cd9b82e840e0315c445653d207"
}

代收成功範例的待簽字串：

fee=25.00&finished_at=2026-10-13 10:12:30&merchant_order_no=MO20261013-0001&order_no=C202610131000051230000&received_amount=1000.37&settlement_amount=975.37&status=success