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）避免混淆