# Coinepay OpenAPI

> Coinepay OpenAPI v1.1 — 虛擬卡接入對外文件:HMAC 鑑權、冪等性、Webhook、錯誤碼、程式碼樣例。

本索引按 [llmstxt.org](https://llmstxt.org) 規範組織。完整正文見 [llms-full.txt](/zh-TW/llms-full.txt)。

## 指南

- [HMAC 鑑權](/zh-TW/guide/authentication): Coinepay OpenAPI 使用 HMAC-SHA256 鑑權，4 個請求頭完成簽名 + 防重放。
- [錯誤碼](/zh-TW/guide/error-codes): Coinepay OpenAPI 錯誤碼 message_key → HTTP 狀態 → 中英文釋義對照表。
- [冪等鍵](/zh-TW/guide/idempotency): Coinepay OpenAPI 寫介面必須傳 Idempotency-Key 頭。同 key 同 body 24 小時去重。
- [ID 與字首](/zh-TW/guide/ids-and-prefixes): Coinepay OpenAPI 所有對外資源 ID 都帶業務字首。請保留字首原樣傳回。
- [概述](/zh-TW/guide/overview): Coinepay OpenAPI v1.2 是一組 HMAC 鑑權的 HTTPS REST API，專注於虛擬卡的開卡、充值與狀態查詢。
- [快速開始](/zh-TW/guide/quickstart): 5 分鐘跑通你的第一個 OpenAPI 請求 —— 列出可用卡頭。
- [限流](/zh-TW/guide/rate-limit): Coinepay OpenAPI 按 (AppID, IP) 維度做令牌桶限流，超過返回 429。
- [沙箱與測試](/zh-TW/guide/sandbox): v1.2 不提供獨立沙箱，建議用真實賬號 + 小額測試，並搭配 webhook.site 接收器。
- [Webhook 規範](/zh-TW/guide/webhooks): Coinepay 透過 HMAC 簽名的 Webhook 推送開卡、充值、銷卡等非同步事件。

## API 參考

- [API 參考](/zh-TW/api/): Coinepay OpenAPI v1.2 介面列表 —— 12 個 endpoint，全部 POST，統一 HMAC 鑑權。
- [申請虛擬卡](/zh-TW/api/card-apply): 非同步開卡介面。返回 card_id 與初始 status，開卡完成後透過 webhook 推送。POST /api/v1/openapi/card/apply
- [列卡配置](/zh-TW/api/card-configs-list): 查詢某個卡頭下可選的套餐配置（含費率、首充、月費等）。POST /api/v1/openapi/card_configs/list
- [凍結卡片](/zh-TW/api/card-freeze): 凍結一張已啟用的虛擬卡，使其無法再用於支付。POST /api/v1/openapi/card/freeze
- [列卡頭](/zh-TW/api/card-headers-list): 檢視當前賬號可申請的虛擬卡卡頭列表。POST /api/v1/openapi/card_headers/list
- [查詢卡片資訊](/zh-TW/api/card-info): 查詢卡的狀態、餘額，以及（可選）完整 PAN / CVV / 到期日。POST /api/v1/openapi/card/info
- [建立充值](/zh-TW/api/card-recharge): 非同步充值介面。返回 transaction_id，結果透過 webhook 推送。POST /api/v1/openapi/card/recharge
- [卡片交易列表](/zh-TW/api/card-transactions-list): 查詢某一張指定虛擬卡的交易明細。POST /api/v1/openapi/card/transactions/list
- [解凍卡片](/zh-TW/api/card-unfreeze): 解凍一張透過 OpenAPI 凍結介面凍結的卡片。POST /api/v1/openapi/card/unfreeze
- [列出銀行卡](/zh-TW/api/cards-list): 列出當前 AppID 名下所有虛擬卡，支援狀態/日期/餘額過濾。POST /api/v1/openapi/cards/list
- [首充預覽](/zh-TW/api/first-deposit-preview): 只讀試算開卡首充（底額 + 超額手續費 + 到卡金額 + 錢包凍結合計）。POST /api/v1/openapi/card/first_deposit/preview
- [交易列表](/zh-TW/api/transactions-list): 查詢你名下所有虛擬卡的交易明細。POST /api/v1/openapi/transactions/list
- [Webhook 事件歷史](/zh-TW/api/webhook-events-list): 查詢當前賬號的 webhook 投遞歷史，用於排查 webhook 投遞問題。POST /api/v1/openapi/webhook_events/list

## 程式碼樣例

- [程式碼樣例](/zh-TW/examples/): Python / Node.js / Go / Java / PHP / cURL 複製即用的客戶端實現。
- [cURL](/zh-TW/examples/curl): cURL + openssl 命令列呼叫 OpenAPI —— 適合快速驗證。
- [Go](/zh-TW/examples/go): Go 1.21+ 客戶端實現 —— 僅依賴標準庫。
- [Java](/zh-TW/examples/java): Java 11+ 客戶端實現 —— 僅依賴 JDK 標準庫（HttpClient + javax.crypto）。
- [Node.js](/zh-TW/examples/nodejs): Node.js 18+ 客戶端實現 —— 僅依賴標準庫 crypto + native fetch。
- [PHP](/zh-TW/examples/php): PHP 7.4+ 客戶端實現 —— 僅依賴 cURL 擴充套件（預設開啟）。
- [Python](/zh-TW/examples/python): Python 3.6+ 客戶端實現 —— HMAC 簽名 + Webhook 驗籤。

## 參考資料

- [更新日誌](/zh-TW/reference/changelog): Coinepay OpenAPI 版本與變更記錄。
- [常量字典](/zh-TW/reference/constants): Coinepay OpenAPI v1.2 所有不變的常量值 —— 路徑字首、超時、限制、簽名規範。

## 其他

- [Coinepay OpenAPI v1.2](/zh-TW/): 虛擬卡接入對外文件 — HMAC 鑑權、冪等性、Webhook、錯誤碼與程式碼樣例。