查詢與對帳

三種查詢

想知道	用這支	備註
某一筆交易的最新狀態	`GET /transactions/{id}`	用 27 字元的 `id` 查，才會有 `productDetails`
某個訂單的所有付款嘗試	`GET /order/{orderId}/transactions`	只有 API 交易，含失敗與定期定額各期；一次回傳全部
一段期間的所有款項	`GET /transactions?start=&end=`	每頁 50 筆，由新到舊；包含非 API 的款項
定期定額的狀態	`GET /subscriptions/{id}`	用 `S` 開頭的編號或內部 id

交易列表的範圍

期間與分頁

start 與 end 要一起帶，以台北時間的整天計算：start 當天 00:00 到 end 當天 23:59:59。
日期可以寫 2026-09-01，或 Unix 毫秒時間戳。只帶一個或格式錯誤會回 500 F0001（Invalid date）。
依交易建立時間篩選，不是付款時間。
回應的 page 不是 null 時，把它原封不動放進下一次請求的 ?page=，直到 page 是 null。

async function listAll(start, end) {
  const all = [];
  let page = null;
  do {
    const qs = new URLSearchParams({ start, end, ...(page ? { page } : {}) });
    const res = await fetch(`https://payment-api.oen.tw/transactions?${qs}`, {
      headers: { Authorization: `Bearer ${process.env.OEN_API_TOKEN}` },
    });
    const result = await res.json();
    if (result.code !== "S0000") throw new Error(`${result.code} ${result.message}`);
    all.push(...result.data.transactions);
    page = result.data.page;
  } while (page);
  return all;
}

建議的對帳流程

每 15 分鐘：處理還沒有結果的訂單（做法見沒收到通知時）。
每天：用 GET /transactions 列出前一天建立的款項，只取 P 開頭的項目，和你的訂單逐筆比對：
- 你的系統是「已付款」，應援是 failed 或 initiated：查明原因，不要出貨。
- 應援是 charged 或 claimed，你的系統不是「已付款」：補標。
- 同一個 orderId 有兩筆以上成功：退款多的那筆。
每次撥款後：到 CRM「撥款列表」匯出撥款細項，核對手續費與撥款金額。見查詢交易與對帳。

查詢的注意事項

請不要高頻率地輪詢單筆交易。付款通知到了再查，或用上面的定期工作即可。
交易剛完成的極短時間內，查到的可能還是舊狀態，稍等幾秒再查。
用 P 開頭的交易編號查詢單筆時，回應不含 productDetails 與 numberOfPeriods。
回應裡沒有 currency 欄位，Payment API 的交易都是新台幣。