跳到內容
應援科技應援金流文件

API 參考

在 ChatGPT 開啟在 Claude 開啟

這裡是 Payment API 每一支端點的完整規格。第一次串接請先看快速開始。

所有欄位、限制與錯誤碼都依正式環境 v10.3.1.1 的程式核對，並依 v10.3.5.3 補上之後的變更；交易的 invoice 欄位與發票通知依 v10.3.3.2 核對。也可以下載 OpenAPI 定義檔，匯入 Postman 等工具。

網址

Section titled “網址”
環境 API 結帳頁
正式 https://payment-api.oen.tw https://{merchantId}.oen.tw
測試 https://payment-api.testing.oen.tw https://{merchantId}.testing.oen.tw

驗證

Section titled “驗證”

每個請求都帶：

Authorization: Bearer <token>
Content-Type: application/json
  • token 在 CRM 產生，測試與正式環境各一把，不能互用。見驗證與 token。
  • Bearer 要照這個大小寫，中間只有一個空白。
  • 有 body 的請求要帶 merchantId，而且必須是 token 所屬的網域。
  • 只能從伺服器呼叫。API 不支援瀏覽器跨網域請求，token 也不能放在前端。

回應格式

Section titled “回應格式”

成功時 HTTP 200：

{ "code": "S0000", "data": { }, "message": "" }

失敗時：

{ "code": "V0001", "data": {}, "message": "must have required property 'orderId'" }
  • 程式判斷請看 code，message 的文字可能調整。
  • 付款結果不明時是 HTTP 409，另外帶 "retryable": false，見 C026。
  • 個人身分商家被風控拒絕時（K0001），另外帶 detail。
  • 沒有值的欄位不會出現在回應裡。
  • 找不到路徑時回 404、不支援的 HTTP method 回 405，body 是純文字，不是上面的 JSON 格式。
  • 被正式環境的 IP 白名單擋下時回 403，body 只有 message 欄位（通常是 Forbidden），沒有 code。

欄位驗證

Section titled “欄位驗證”
  • body 必須是合法的 JSON，否則回 500 F0001。
  • 規格裡沒有的欄位會被忽略，不會報錯。所以欄位名稱拼錯時不會有任何提示，請對照各端點的欄位表。例如 Payment API 沒有 webhookUrl、cancelUrl 這類欄位，付款通知網址在 CRM 設定。
  • 驗證失敗回 400 V0001，message 會列出所有不符合的規則，但不一定有欄位名稱。

分頁

Section titled “分頁”

查詢交易列表與查詢商店定期購列表每頁 50 筆。回應的 page 是下一頁的分頁標記，原封不動放進下一次請求的 ?page=；沒有下一頁時是 null。請以 page 是不是 null 判斷有沒有下一頁，不要看這一頁有幾筆。標記無效時回 500 F0001。

時間

Section titled “時間”
  • 回應的時間都是 UTC 的 ISO 8601 字串，例如 2026-09-28T02:40:25.502Z。
  • 你送出的日期（startDate、expectedPayoutDate）格式是 yyyy/MM/dd，以台北日期解讀。
  • 定期定額每天台北時間上午 9 點扣款。

ID

Section titled “ID”
名稱 格式 用在
交易 id／transactionId 27 字元英數 組結帳頁網址、付款通知、查詢交易明細
交易編號 transactionHid P + 日期 + 8 碼，共 17 字元，例如 P20260928AB12CD34 退款、對帳、CRM 搜尋
定期定額編號 S + 日期 + 8 碼，共 17 字元 查詢與取消定期定額
orderId 你自己的訂單編號 用訂單編號查詢

冪等性與頻率限制

Section titled “冪等性與頻率限制”

Idempotency-Key

Section titled “Idempotency-Key”

下列端點支援 Idempotency-Key header：POST /checkout、POST /checkout-subscription、POST /checkout-schedule、POST /checkout-token、POST /token/transactions、POST /token/subscriptions、POST /refunds/{transactionHid}、PUT /subscriptions/{subscriptionHid}。

Idempotency-Key: A20260928001-charge-1
  • key 是 1 到 255 個 ASCII 可見字元（不含空白）。格式不符回 400 V0001（INVALID_IDEMPOTENCY_KEY）。建議用訂單編號加上用途與次數。
  • 範圍是「你的網域＋端點」，同一把 key 用在不同端點互不影響。
  • 同一把 key、相同的請求（method、路徑與 body 都相同）重送：直接回第一次的狀態碼與 body，回應 header 帶 Idempotency-Replayed: true，不會再扣款或退款。
  • 同一把 key、不同的請求：回 422 I0001。
  • 第一次的請求還在處理：回 409 I0002，請稍後用同一把 key 重送。
  • POST /token/transactions、POST /token/subscriptions、POST /refunds/{transactionHid}：第一次的請求已經開始扣款或退款，超過 5 分鐘仍沒有結果時，回 409 I0003，detail.resourceId 是交易編號（P 開頭）或定期定額編號（S 開頭）。同一把 key 不會再執行，請用這個編號或訂單編號查詢結果。
  • 四支建立結帳頁的 API（/checkout、/checkout-subscription、/checkout-schedule、/checkout-token）沒有這層保護：如果第一次的請求已經建立資料、但回應沒有保存下來（例如中途中斷），5 分鐘後用同一把 key 重送可能再建立一筆。結果不明時，請依資源種類查詢交易或定期定額；綁卡請求無法用訂單編號查回，請聯絡應援確認。
  • 取消定期定額也沒有這層保護，但重送不會建立新的定期定額；結果不明時，請用定期定額編號查詢目前狀態。
  • 只有進入處理前的欄位格式驗證失敗不會用掉這把 key。處理過程中回的 400 V0001（例如 PRODUCT_AMOUNT_NOT_MATCH）可能已經記住，修改內容後請換一把新的 key。
  • 第一次收到 5xx 或 429、而且還沒開始扣款或退款時，不會記住結果，可以用同一把 key 重送；退款確定沒有送出時（例如回 R0001），也可能不記住。其他結果確定的 4xx（例如發卡銀行拒絕）會記住，同一把 key 重送會拿到同一個錯誤。
  • key 保留 24 小時，之後同一把 key 視為新的請求。
  • 不帶 header 時行為不變：同樣的請求送兩次，就會建立兩筆交易。

頻率限制

Section titled “頻率限制”
  • 目前沒有對個別商家限制請求頻率，但請不要高頻率輪詢；日後可能開始限制。

端點一覽

Section titled “端點一覽”
Method Path 說明
POST /checkout 建立單次付款
POST /checkout-subscription 建立定期定額
POST /checkout-schedule 建立預約定期定額
POST /checkout-token 建立綁卡頁
POST /token/transactions 用 token 扣款
POST /token/subscriptions 用 token 建立定期定額
GET /transactions/{id} 查詢交易明細
GET /transactions 查詢交易列表
GET /order/{orderId}/transactions 用訂單編號查詢交易
POST /refunds/{transactionHid} 退款
GET /subscriptions/{id} 查詢定期定額明細
PUT /subscriptions/{subscriptionHid} 取消定期定額
POST /subscriptions/{subscriptionHid}/change-card-checkout 建立換卡頁
GET /subscriptions 查詢商店定期購訂單列表

需要傳送完整卡號的 API 必須符合 PCI DSS 規範，不在本站公開。若你的情境確實需要，請聯絡業務人員個別討論。