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。