# Coinepay OpenAPI

> Coinepay OpenAPI v1.1 — 虚拟卡接入对外文档:HMAC 鉴权、幂等性、Webhook、错误码、代码样例。

本索引按 [llmstxt.org](https://llmstxt.org) 规范组织。完整正文见 [llms-full.txt](/zh-CN/llms-full.txt)。

## 指南

- [HMAC 鉴权](/zh-CN/guide/authentication): Coinepay OpenAPI 使用 HMAC-SHA256 鉴权，4 个请求头完成签名 + 防重放。
- [错误码](/zh-CN/guide/error-codes): Coinepay OpenAPI 错误码 message_key → HTTP 状态 → 中英文释义对照表。
- [幂等键](/zh-CN/guide/idempotency): Coinepay OpenAPI 写接口必须传 Idempotency-Key 头。同 key 同 body 24 小时去重。
- [ID 与前缀](/zh-CN/guide/ids-and-prefixes): Coinepay OpenAPI 所有对外资源 ID 都带业务前缀。请保留前缀原样传回。
- [概述](/zh-CN/guide/overview): Coinepay OpenAPI v1.2 是一组 HMAC 鉴权的 HTTPS REST API，专注于虚拟卡的开卡、充值与状态查询。
- [快速开始](/zh-CN/guide/quickstart): 5 分钟跑通你的第一个 OpenAPI 请求 —— 列出可用卡头。
- [限流](/zh-CN/guide/rate-limit): Coinepay OpenAPI 按 (AppID, IP) 维度做令牌桶限流，超过返回 429。
- [沙箱与测试](/zh-CN/guide/sandbox): v1.2 不提供独立沙箱，建议用真实账号 + 小额测试，并搭配 webhook.site 接收器。
- [Webhook 规范](/zh-CN/guide/webhooks): Coinepay 通过 HMAC 签名的 Webhook 推送开卡、充值、销卡等异步事件。

## API 参考

- [API 参考](/zh-CN/api/): Coinepay OpenAPI v1.2 接口列表 —— 12 个 endpoint，全部 POST，统一 HMAC 鉴权。
- [申请虚拟卡](/zh-CN/api/card-apply): 异步开卡接口。返回 card_id 与初始 status，开卡完成后通过 webhook 推送。POST /api/v1/openapi/card/apply
- [列卡配置](/zh-CN/api/card-configs-list): 查询某个卡头下可选的套餐配置（含费率、首充、月费等）。POST /api/v1/openapi/card_configs/list
- [冻结卡片](/zh-CN/api/card-freeze): 冻结一张已激活的虚拟卡，使其无法再用于支付。POST /api/v1/openapi/card/freeze
- [列卡头](/zh-CN/api/card-headers-list): 查看当前账号可申请的虚拟卡卡头列表。POST /api/v1/openapi/card_headers/list
- [查询卡片信息](/zh-CN/api/card-info): 查询卡的状态、余额，以及（可选）完整 PAN / CVV / 到期日。POST /api/v1/openapi/card/info
- [创建充值](/zh-CN/api/card-recharge): 异步充值接口。返回 transaction_id，结果通过 webhook 推送。POST /api/v1/openapi/card/recharge
- [卡片交易列表](/zh-CN/api/card-transactions-list): 查询某一张指定虚拟卡的交易明细。POST /api/v1/openapi/card/transactions/list
- [解冻卡片](/zh-CN/api/card-unfreeze): 解冻一张通过 OpenAPI 冻结接口冻结的卡片。POST /api/v1/openapi/card/unfreeze
- [列出银行卡](/zh-CN/api/cards-list): 列出当前 AppID 名下所有虚拟卡，支持状态/日期/余额过滤。POST /api/v1/openapi/cards/list
- [首充预览](/zh-CN/api/first-deposit-preview): 只读试算开卡首充（底额 + 超额手续费 + 到卡金额 + 钱包冻结合计）。POST /api/v1/openapi/card/first_deposit/preview
- [交易列表](/zh-CN/api/transactions-list): 查询你名下所有虚拟卡的交易明细。POST /api/v1/openapi/transactions/list
- [Webhook 事件历史](/zh-CN/api/webhook-events-list): 查询当前账号的 webhook 投递历史，用于排查 webhook 投递问题。POST /api/v1/openapi/webhook_events/list

## 代码样例

- [代码样例](/zh-CN/examples/): Python / Node.js / Go / Java / PHP / cURL 拷贝即用的客户端实现。
- [cURL](/zh-CN/examples/curl): cURL + openssl 命令行调用 OpenAPI —— 适合快速验证。
- [Go](/zh-CN/examples/go): Go 1.21+ 客户端实现 —— 仅依赖标准库。
- [Java](/zh-CN/examples/java): Java 11+ 客户端实现 —— 仅依赖 JDK 标准库（HttpClient + javax.crypto）。
- [Node.js](/zh-CN/examples/nodejs): Node.js 18+ 客户端实现 —— 仅依赖标准库 crypto + native fetch。
- [PHP](/zh-CN/examples/php): PHP 7.4+ 客户端实现 —— 仅依赖 cURL 扩展（默认开启）。
- [Python](/zh-CN/examples/python): Python 3.6+ 客户端实现 —— HMAC 签名 + Webhook 验签。

## 参考资料

- [更新日志](/zh-CN/reference/changelog): Coinepay OpenAPI 版本与变更记录。
- [常量字典](/zh-CN/reference/constants): Coinepay OpenAPI v1.2 所有不变的常量值 —— 路径前缀、超时、限制、签名规范。

## 其他

- [Coinepay OpenAPI v1.2](/zh-CN/): 虚拟卡接入对外文档 — HMAC 鉴权、幂等性、Webhook、错误码与代码样例。