API開發文件

本 OpenAPI 採用 RSA2048 + SHA512withRSA 雙向簽名 進行身份認證與防篡改：請求由商戶私鑰簽名、平台用商戶公鑰驗簽；響應/通知由平台私鑰簽名、商戶用平台公鑰驗簽。傳輸保密由 HTTPS 保證，不再做 jsonData 加密、不使用 token。

金額單位一律為「元」，保留 2 位小數，使用字串傳輸（例："100.00"）。所有請求 Content-Type: application/json，UTF-8。

1. 商戶用自己的私鑰對簽名串做 SHA512withRSA 簽名，Base64 後放入 sign。
2. 平台校驗時間戳視窗（±5 分鐘）與來源 IP 白名單。
3. 平台用商戶公鑰對原始報文驗簽，通過後解析 jsonData 執行業務並寫審計日誌。
4. 平台用平台私鑰對結果簽名後返回；商戶用平台公鑰驗簽。

防重放：HTTPS + 時間戳 ±5 分鐘視窗 + out_trade_no 業務冪等（重複下單/出金返回同一單，查詢只讀，無資損）。

請求 Body（JSON）

響應 Body（JSON）

{
  "code": "0000",
  "message": "success",
  "data": {
    "businessSubjectId": "10001",
    "jsonData": "{...業務返回明文...}",
    "timestamp": "1700000000000",
    "sign": "平台私鑰簽名(Base64)"
  }
}

早期失敗（未知商戶/驗簽失敗/IP 不符等）返回明文錯誤信封，data 為 null，無 sign。

演算法 SHA512withRSA（PHP: OPENSSL_ALGO_SHA512），簽名結果 Base64。

請求簽名串（順序固定，原樣拼接）

signStr = jsonData + "&" + businessSubjectId + "&" + timestamp
sign    = base64( RSA_SHA512_sign(signStr, 商戶私鑰) )

響應/通知驗簽串

響應: jsonData + "&" + businessSubjectId + "&" + timestamp
通知: jsonData + "&" + businessSubjectId + "&" + timestamp + "&" + businessType

實作紅線：驗簽必須針對原始報文中的 jsonData 字串值，禁止把解析後的物件重新 json_encode 再驗——鍵序/轉義一變簽名即失效。請用原始請求體（如 php://input）取 jsonData。

提交方式：POST

地址：閘道地址 + /Openapi_Debug_ping.html

驗簽通過後原樣回顯 jsonData，用於聯通與加簽自測。

提交方式：POST　地址：閘道地址 + /Openapi_Collect_create.html

jsonData 業務欄位

返回 jsonData

同一 out_trade_no 重複下單返回同一訂單與同一張卡（冪等，不重複鎖卡）。

收款成功時，平台以信封格式 POST 到 notify_url，businessType=COLLECT_NOTIFY（參與簽名）。商戶用平台公鑰驗簽後，回傳純文字 SUCCESS 即停止；否則平台最多重試 5 次（每整點 1 次）。

通知 jsonData 欄位

提交方式：POST　地址：閘道地址 + /Openapi_Collect_query.html

jsonData：{ "out_trade_no": "..." }

返回 jsonData

提交方式：POST　地址：閘道地址 + /Openapi_Payout_apply.html

jsonData 業務欄位

返回 jsonData：{ trade_no, out_trade_no, amount, fee }

提交方式：POST　地址：閘道地址 + /Openapi_Payout_query.html

jsonData：{ "out_trade_no": "..." }

出金放款/駁回時，平台以信封格式 POST 到 notify_url，businessType=PAYOUT_NOTIFY（參與簽名）。商戶驗簽後回 SUCCESS 停止；最多 5 次、每整點重試。

收款（銀行卡）渠道編碼為 999。如需指定可在下單 jsonData 傳 pay_bankcode，預設 999。

官方 PHP Demo：docs/sdk/openapi_demo.php；凍結測試向量（測試金鑰 + 已知 jsonData/timestamp → 期望 sign）：docs/sdk/test_vector.json（由自檢工具 php cli.php openapiSelfTest 產生）。

請求範例

POST /Openapi_Debug_ping.html
Content-Type: application/json

{
  "businessSubjectId": "10001",
  "jsonData": "{\"msg\":\"hello\",\"n\":1}",
  "timestamp": "1700000000000",
  "sign": "<商戶私鑰 SHA512withRSA 簽名(Base64)>"
}

簽名串（用於計算 sign）

{"msg":"hello","n":1}&10001&1700000000000