概述

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 不提供独立沙箱。请用真实账号 + 小额测试。详见 沙箱与测试。