Opay 開發者平台v1.0.0 Beta
供獨立站與 WooCommerce 後端調用的 REST API — 帳本、Connect 與收款連結，全部對接 opay.com.hk 中台。
認證機制
所有伺服器端請求須在 HTTP Header 攜帶商戶插件密鑰。請先在商戶中心註冊並完成 KYC，於「設置」生成 opay_sk_* 密鑰。
切勿在瀏覽器 JavaScript 或 App 中暴露 opay_sk_* 密鑰。
X-Opay-Api-Key: opay_sk_live_…X-Opay-Portal-Key（同等效力）
商戶隔離（Tenant Isolation）
每把 opay_sk_* 僅授權一個商戶 UUID。若密鑰與 URL 中的 {merchant_id} 不一致，API 返回 403 Forbidden，code 為 TENANT_MISMATCH。
Base URL
https://www.opay.com.hk路徑格式：/api/merchants/{merchant_id}/…
快速入門（5 分鐘）
- 在 /login 註冊並完成合規開戶（KYC）
- 商戶中心 → 設置 → 生成 API 密鑰（opay_sk_*）並複製 Merchant ID
- 從伺服器以 X-Opay-Api-Key 調用 GET /api/merchants/{id}/overview
- 讀取 opay_balance.spendable_balance 判斷可花餘額
核心端點
| Method | Path | Description |
|---|---|---|
| GET | /api/merchants/{merchant_id}/overview | 帳本桶 + 可花餘額 + Risk Tier |
| GET | /api/merchants/{merchant_id}/balance | 原始 balances 表行 |
| GET | /api/merchants/{merchant_id}/ledger | 收款 + 退款統一流水 |
| GET | /api/merchants/{merchant_id}/connect | Opay Connect 帳戶狀態 |
| POST | /api/merchants/{merchant_id}/connect | 發起 Connect 開戶 |
| POST | /api/merchants/{merchant_id}/payment-links | 建立 Payment Link（需 active） |
Live / Test 密鑰
- opay_sk_live_* — 生產環境帳本與清算
- opay_sk_test_* — 整合測試（僅 GET 唯讀；寫入操作返回 403）
請求簽名（HMAC）
WooCommerce 插件與 SDK 須附帶 X-Opay-Timestamp 與 X-Opay-Signature。超過 5 分鐘的請求會被拒絕。
HMAC-SHA256(secret, timestamp + rawBody) → hex出站 Webhooks
以商戶中心 Session 註冊 HTTPS 端點，Opay 會 POST 簽名 JSON 事件至您的伺服器。
payment.succeeded · payment.failed · refund.created · payout.paid · payout.failed · connect.updated · balance.updated
Node.js SDK
官方客戶端，自動 HMAC 簽名 — 路徑： packages/opay-node
代碼示例
curl -X GET "https://www.opay.com.hk/api/merchants/YOUR_MERCHANT_UUID/overview" \ -H "X-Opay-Api-Key: opay_sk_live_YOUR_SECRET_KEY" \ -H "Content-Type: application/json"
OpenAPI 規格書
OpenAPI 3.0 機器可讀文檔，可導入 Swagger、Redoc 或 Postman。