ID 与前缀

Coinepay OpenAPI 所有对外资源 ID 都是带前缀的字符串，不直接暴露内部数字主键。客户回传时必须保留前缀。

前缀总表

资源	前缀	示例	出现位置
卡	card_	card_12345	apply 响应 / 后续接口的 card_id 字段
套餐	pkg_	pkg_67	card_configs/list 返回 / apply 请求传入
卡头	hdr_	hdr_5	card_headers/list 返回 / apply 请求传入
充值订单	txn_	txn_OO20260429110012abc	recharge 响应 / webhook payload
Webhook 事件	evt_	evt_550e8400-e29b-41d4-a716-446655440000	webhook_events/list 返回

Webhook 中也保持一致

Webhook payload 中所有 ID 同样带前缀。Webhook-Id 头去掉 evt_ 即原始 UUID。

transaction_id 是不透明字符串

把 txn_<...> 当作不透明字符串用来存储、查询、对账。txn_ 前缀之后的内部结构由服务端生成，不保证跨版本 / 跨 provider 稳定 —— 不要解析、切割或正则匹配。内部订单引用故意不对外暴露。

校验规则

错误情况	返回
缺前缀（如传 5 而非 hdr_5）	400 openapi_invalid_header_id
ID 不存在 / 不属于当前账号	400 openapi_invalid_*_id（与"缺前缀"返回相同 message_key —— 防泄漏）

不区分"格式错"和"不存在"

openapi_invalid_*_id 同时覆盖：

• 前缀缺失
• ID 不属于当前 AppID 的账号
• ID 不存在

服务器故意不区分 — 防止枚举攻击者通过响应差异探测有效 ID 范围。

不会暴露的内部字段

每个接口文档中列出的响应字段表即完整契约。内部数据库主键、提供方订单引用、中间计算字段和内部标签等不会通过 OpenAPI 返回。

如发现响应中出现已记录字段表之外的内容，请反馈给 Coinepay 团队。

使用建议

• 客户端存储时包含前缀，回传时也保持原样（不要拆出数字部分）
• 日志/告警中带上完整 ID（card_12345），便于排查
• 与你的内部 ID 区分：card_xxx 是 Coinepay 的，建议你的内部 ID 用其他前缀（如 kart_xxx）避免混淆