更新紀錄

文件

新增測試卡號：付款成功、3D 驗證、付款失敗各用哪一組卡號，以及到期日、安全碼、持卡人姓名的填法。
環境與測試原本請你向聯絡人索取測試卡號，現在直接列在文件。快速開始、單次付款、定期定額、存卡、付款通知、上線檢查清單與 WooCommerce 外掛的測試步驟也加上對應的卡號。

新增子網域開通 API（需開通）：母網域用 API 為旗下商家申請子網域、上傳文件、送審與撤回，開通後取得子網域的 Payment API token，並接收審核進度通知。

Payment API 文件從 Postman 移到本站，依正式環境 v10.3.1.1 逐項核對。舊的 Postman 文件保留但不再更新。
新增：存卡與後續扣款（/checkout-token、/token/transactions、/token/subscriptions）、付款通知的完整欄位、錯誤碼一覽、固定 IP 白名單、環境與測試、商家操作指南。
更正舊文件：
- 所有建立交易的 API 都必須帶 productDetails，品項合計要等於 amount。
- 付款通知最多送 3 次，間隔約 2 秒、4 秒（舊文件寫 2、4、6 秒）。
- 退款不只信用卡：Apple Pay、LINE Pay、超商代碼、ATM 都可以用 API 退。amount 不帶就是全額。
- POST /checkout-schedule 的回應是 subscriptionHid，不是 transactionHid。
- 失敗導回的 payment_error 不會是 V0001。
- 「金額大於 100 元成功」不是應援系統的規則，請不要依賴。
新增 OpenAPI 定義檔與 llms.txt。

付款通知可以加上簽章：在 CRM「總設定」→「開發者」→「應援金流設定」產生「付款通知簽章密鑰」後，每則通知帶 OenPay-Signature。每則通知也都多了 OenPay-Event-Id 與 OenPay-Delivery-Attempt。見確認通知的真假。
successUrl、failureUrl 只接受 https://、http:// 開頭的網址，其他 scheme 回 400 V0001；App 自訂 scheme 目前不支援。
正式環境的非預期系統錯誤，message 一律是 SYSTEM_ERROR，不再帶內部訊息與 detail。
指示制撥款的網域：交易被撥款指示預留時不能退款，API 目前回 500 F0001。見退款。
測試環境可以在 CRM 的交易明細模擬超商代碼、ATM 的付款結果。見環境與測試。
OenPay Embed：建立退款一定要帶 Idempotency-Key；綁卡與 off-session 扣款需由應援開通，付款時存卡（setupFutureUsage）不再支援；SDK 更新到 v1.5.0。見 Embed。
Subscription API：CRM「訂閱管理」改為需要開通的付費功能，已建立的金鑰不受影響。見 Subscription API。

建立交易、退款、取消定期定額的 8 支 API 支援 Idempotency-Key：24 小時內用同一把 key 重送相同請求，回應已保存時會拿到第一次的回應；用 token 扣款與退款另有防重複扣款、退款的保護。新增錯誤碼 I0001～I0003。見 API 參考。
token 加上到期日：之後產生的 token 一年後到期；重新產生後舊 token 最多還能用 7 天（不超過原本的到期日）。過期回 401 A0002。之前產生的 token 不受影響。見驗證與 token。
正式環境 IP 改在 CRM「總設定」→「開發者」→「正式環境設定」送出，最多 3 組。見固定 IP 白名單。
新增建立換卡頁，消費者可以自己更換定期定額的信用卡，換卡成功送 subscription_card_changed 通知。
用 token 扣款新增錯誤碼 T0009（網域設定不能免 3D 扣款）、T0010（同一張卡短時間內被拒絕太多次）。
定期定額可以設定首期折扣 firstPeriodDiscount（需開通）。
PUT /subscriptions/{subscriptionHid} 沒帶 body 改回 400 V0001（原本是 500）。
退款後自動開立折讓擴大到 Apple Pay，以及完成匯款的超商代碼與 ATM。
OenPay Embed 可以開立電子發票，見 Embed。

查詢交易（GET /transactions/{id}、GET /transactions、GET /order/{orderId}/transactions）的每筆交易多了 invoice 物件：發票號碼、狀態、開立時間與隨機碼。沒有發票時是 null。
新增發票通知 invoice_issued（發票已開立）、invoice_voided（發票已作廢），要請應援開啟。見電子發票號碼與狀態。
POST /checkout 新增 strictPaymentMethods：true 時只顯示 allowedPaymentMethods 裡的方式，新增錯誤碼 V0004～V0007。
結帳頁不再顯示網域沒有開通的付款方式。

allowedPaymentMethods 在結帳頁實際生效：結帳頁照清單顯示付款方式並把關。信用卡仍然一定會出現，["cvs"] 是信用卡加超商代碼。
新增 409 C026（付款結果不明），回應帶 "retryable": false。
綁卡頁（/checkout-token）與預約定期定額：部分收單機構綁卡時會先授權新台幣 1 元再退回，頁面會事先告知消費者。
定期定額的結帳頁，付款人 Email 改為必填。
修正定期定額在特定情況下停止扣款的問題。