API 基礎規則

Base URL、路徑命名、金額/時間格式、分頁、排序、回應格式、rate limit——串接前先看這頁，其他頁面都假設你已經知道這些規則。

Base URL、路徑命名與版本

所有端點都在你的環境網址的 /api 底下（例如 $REBATE_PAY_BASE_URL/api/Product）。路徑規則是 /api/{資源}[/{資源Id}][/{動作}]：資源用 PascalCase 單數名詞（Product、PaymentLink、WebhookEndpoint），單筆資源帶 {資源Id}，非 CRUD 的動作放在最後（/api/Subscription/{subscriptionId}/Cancel、/api/Payment/{paymentId}/Reconcile）。路徑比對不分大小寫，但文件一律以 PascalCase 為準。

HTTP 方法	用途	範例
`GET`	查詢列表或單筆	`GET /api/Product`、`GET /api/Product/{productId}`
`POST`	建立資源或執行動作	`POST /api/Product`、`POST /api/Refund`、`POST /api/PaymentLink/{paymentLinkId}/Archive`
`PUT`	更新資源（只送要改的欄位）	`PUT /api/Product/{productId}`
`DELETE`	刪除資源	`DELETE /api/PaymentMethod/{paymentMethodId}`

開發者 API 的路徑沒有前綴；ReBate Pay 自己的後台 API 用 Admin*（平台後台）、Merchant*（商家後台）、Member*（消費者錢包）前綴，並改用 JWT 登入（見驗證）。完整規格：GET /api/OpenApi?audience=developer。API 版本用日期字串標示（例如 2026-08-30），會透過 x-rebatepay-version 回應標頭帶回來。

這個 API 目前只服務 Sandbox（測試環境）。任何請求不管有沒有帶 environment 參數，最後都會被視為 sandbox；正式環境端點尚未開放。

物件 ID 格式

每個資源的 ID 都是「前綴 + 隨機字串」，前綴代表資源種類，方便你一眼看出是什麼物件、也方便你的程式做防呆檢查：

前綴	資源
`prod_`	Product
`price_`	Price
`cus_`	Customer
`sub_`	Subscription
`pay_`	Payment
`re_`	Refund
`plink_`	Payment Link
`evt_`	Webhook Event
`wda_`	Webhook Delivery Attempt

金額：整數、無小數位

跟很多金流 API 不一樣：這裡的 amount 不是 cents 之類的最小貨幣單位。TWD 沒有小數位，amount: 200 就是 NT$200，不是 NT$2。如果你的程式碼是照抄別家 API 的「乘以 100」慣例搬過來，會多算 100 倍，請務必調整。

時間：ISO 8601，UTC

所有時間欄位都是 ISO 8601 字串、UTC 時區（例如 2026-08-30T00:00:00.000Z）。畫面顯示台灣時間時，前端會自己轉換；透過 API 拿到的原始欄位一律是 UTC，不要假設是 Asia/Taipei。

分頁：page / pageSize

所有列表端點都用同一套頁碼分頁參數，回應會帶總筆數與總頁數：

參數	說明
`page`	第幾頁，從 1 開始，預設 1
`pageSize`	每頁筆數，1–200，預設 20
回應的 `page`／`pageSize`	實際使用的頁碼與每頁筆數
回應的 `totalCount`／`totalPages`	符合條件的總筆數與總頁數；`page < totalPages` 代表還有下一頁

curl -sS "$BASE/api/Product?page=1&pageSize=20" -H "Authorization: Bearer $API_KEY"
# 下一頁：
curl -sS "$BASE/api/Product?page=2&pageSize=20" -H "Authorization: Bearer $API_KEY"

篩選與排序

參數	說明
`orderBy`	排序欄位（回應裡的欄位名稱，例如 `createdAt`、`amount`），最長 50 字元；不帶則依建立時間新到舊
`orderDirection`	`ASC` 或 `DESC`（預設 `DESC`）
`createdFrom`／`createdTo`	建立時間區間，ISO 8601 date-time
`status`	依端點而定的狀態，用 PascalCase 列舉值（例如 `Active`、`Succeeded`）
`keyword`（或 `q`）	自由文字搜尋，最長 200 字元

欄位與列舉值

JSON 欄位一律 camelCase（customerId、successUrl）。狀態、類型、週期等列舉值一律 PascalCase：例如付款狀態 Pending、Succeeded、Failed、Unknown，訂閱狀態 Trialing、Active、PastDue、Canceled，價格類型 OneTime、Recurring，週期 Month、Year。事件類型維持點號格式（payment.succeeded）。

回應格式

成功時回應本體放在 data；失敗時放在 error，HTTP status 反映錯誤類型。每個回應都帶 x-request-id 標頭，聯絡支援時請提供：

{
  "data": { "id": "plink_...", "status": "Active", "url": "https://.../pay/..." }
}

error.nextAction 是給人看的建議處理方式（目前是 zh-TW），error.code 才是給程式判斷用的穩定字串。完整錯誤碼對照見疑難排解／錯誤碼。

Rate limit

每把 API Key 預設限制每 60 秒 120 次請求（固定時間窗，不是滑動窗）。每個回應都會帶：

標頭	說明
`x-ratelimit-limit`	這個時間窗的總配額
`x-ratelimit-remaining`	這個時間窗還剩幾次
`x-ratelimit-reset`	配額重置時間（Unix timestamp，秒）

超過限制會收到 429 RATE_LIMITED，並帶 Retry-After（秒數）標頭——直接照這個秒數等待再重試，不要用固定的重試間隔硬猜。

重試與 Idempotency-Key

GET 一律可以安全重試。任何會改變資料的財務操作（付款、退款、結帳）都必須帶 Idempotency-Key 標頭，否則直接收到 400 IDEMPOTENCY_KEY_REQUIRED。同一把 key 重送同一個 idempotency key 會拿到原本那次的結果（回應會帶 x-idempotent-replay: true），不會被重複執行。完整說明見退款與 Idempotency。

← 5 分鐘快速開始 Hosted Checkout 與 Payment Link →