概述

Coinepay OpenAPI v1.2 是一組 HMAC 鑑權的 HTTPS REST API，專注於虛擬卡的開卡、充值與狀態查詢。所有介面僅支援 POST 方法，請求與響應均為 application/json。

核心特徵

• 統一 POST 介面：所有 endpoint 都是 POST，便於前後端中介軟體統一攔截。
• HMAC-SHA256 鑑權：4 個請求頭（X-App-Id / X-Timestamp / X-Nonce / X-Signature），無需 OAuth/JWT。
• 冪等性：寫介面要求傳 Idempotency-Key，24 小時去重。
• 業務字首 ID：所有對外資源 ID 都有字首（如 card_12345、pkg_67），不洩漏內部 DB 主鍵。
• Webhook 非同步推送：開卡 / 充值 / 銷卡完成時主動推送，簽名同樣為 HMAC-SHA256。
• 國際化錯誤：透過 Accept-Language 切換中英文 message，同時返回穩定的 message_key 用於程式判斷。

業務範圍（v1.2）

當前版本支援

僅 虛擬卡：virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a

暫不支援

• 實體卡（master_e / visa_h）
• 轉賬介面（transfer）

推薦閱讀順序

1. 快速開始 — 5 分鐘跑通第一個請求
2. HMAC 鑑權 — 必讀：簽名輸入構造規範
3. ID 與字首 — 資源識別符號約定
4. 冪等鍵 — 寫介面的安全重試
5. 錯誤碼 — message_key 字典
6. Webhook 規範 — 接收非同步事件
7. API 參考 — 12 個具體 endpoint 的請求/響應欄位表

介面字首

{base_url}/api/v1/openapi/{endpoint}

環境	base_url
生產	https://api.coinepay.net
開發	http://localhost:8801

僅使用 HTTPS

生產環境必須透過 HTTPS 呼叫 https://api.coinepay.net。API Key 與 HMAC 簽名透過請求頭傳輸，明文 HTTP 會在傳輸途中洩露憑證。請精確固定主機名：base_url 末尾不要加斜槓，也絕不要使用相似域名。

沙箱

v1.2 不提供獨立沙箱。請用真實賬號 + 小額測試。詳見 沙箱與測試。