更新日志

所有破坏性变更（删字段、改语义、改类型）都会升 major 版本并提前公告。新增字段是非破坏性变更。

v1.4（当前）

新增

• 2026-09-08：首充最低金额与免手续费底额拆分。 /card_configs/list 新增 min_first_deposit、/card/first_deposit/preview 新增 min_first_deposit_amount：生效的首充总额最低值（max(initial_deposit / base_amount, 套餐或卡头设置的首充最低)，含底额）。initial_deposit / base_amount 语义不变（1:1 免手续费的部分）。非破坏性新增字段；未设置首充最低的套餐该值等于底额。
• 2026-08-21：新增支持的 card_type 取值 virtual_a（虚拟卡 A 类，与 V / R / G 同一提供方体系）。所有既有端点均可用 —— 列卡头 / 列卡配置 / 首充预览 / 申请虚拟卡 / 充值 / 卡详情（含敏感字段）/ 冻结 / 解冻 / 销卡 / 交易明细 —— 所有出站 webhook（card.opened、card.open_failed、card.recharged、card.recharge_failed、card.closed、card.status_changed）同样覆盖。协议级开卡规则见 A 卡特殊约束：email 始终必填，不收手机号（phone* / use_bound_phone 被忽略），first_name + last_name 必填且不能为空白；违反时在冻结任何资金之前返回 400 virtual_a_required_fields_missing。非破坏性变更 —— 无新端点、无结构变化；按 card_type 分支的客户端需补充新取值。
• 2026-08-21：/card_headers/list 与 /card_configs/list 新增响应字段 kyc_requirement（开卡平台实名要求：require_kyc / kyc_type / kyc_level）。套餐行内为有效值（卡头 > 卡配置 > 卡类型三级合并，即 apply 实际校验口径），卡头行内为未选套餐时的预览。require_kyc=true 且终端账号未达标时 /card/apply 返回 400 kyc_required。非破坏性新增字段；字段结构见卡头列表文档。

变更

• 2026-09-08：/card/apply 开始强制套餐首充最低金额。 first_deposit_amount 必须 ≥ min_first_deposit；套餐把首充最低设得高于底额时该字段变为必填 —— 不传 / 留空（仍默认底额）会被 400 first_recharge_below_min 拒绝（预览以 invalid_reason 同样报告）。未设置首充最低的套餐行为与之前完全一致。请从列卡配置读取 min_first_deposit（或预览的 min_first_deposit_amount）并始终显式传 first_deposit_amount。
• 2026-08-21：客户经理管控卡头改为按账号过滤。 平台交给客户经理管控（由经理按客户放开）的卡头，/card_headers/list 仅在您的账号已绑定有效客户经理、且该经理已对您放开时才返回（对单个账号的设置优先于经理统一设置）；否则服务端过滤、不计入 total —— 此前会照常列出、到开卡才被拒。/card_configs/list、/card/first_deposit/preview 现在提前做同一校验，返回 400 account_manager_bind_required / account_manager_unavailable / account_manager_open_disabled（与 /card/apply 既有错误码一致）。/card_configs/list 同时不再返回客户经理已对该账号关闭的套餐。存量卡不受影响。对于从列表接口动态获取 header_id / package_id 的对接方为非破坏性变更；硬编码了卡头 ID 的对接方建议刷新。详见错误码。
• 2026-08-21：/card_headers/list 的 require_email / require_phone 改为生效值。 解析口径与开卡校验完全一致（卡类型默认 → 卡头覆盖 → 协议规则：virtual_g 两者必填、virtual_a 邮箱必填且不收手机号、virtual_v 两者可选），且不再为 null。此前仅透传卡头原始配置，可能与开卡校验不一致。非破坏性（字段名与类型不变）。
• 2026-08-21：/card/apply 上带上下文包装的业务错误改为以 400 + message_key 返回。 virtual_a_required_fields_missing、virtual_g_name_invalid 这类校验失败此前会被误归类为 500 openapi_apply_card_failed，现在返回 400 + 文档中的 key。已把 4xx key 当作终态处理的对接方无需改动。
• 2026-08-21：/card_headers/list 不再返回非虚拟卡卡头。 「仅虚拟卡」过滤下推到查询层（不计入 total）；此前平台若配置了实体卡等非虚拟卡卡头会被照常列出，拿去 /card_configs/list / /card/apply 才返回 400 openapi_card_type_not_supported。对只消费虚拟卡卡头的对接方无感知。

v1.3

新增

• 2026-08-03：敏感卡信息支持用户二次验证自助获取。/card/info 传 with_sensitive=true 不再要求管理员为凭证开通权限：随请求提交账户的交易认证凭据（email_code / pin / two_fa_code / sms_code）即可 —— 与 Web 端查看 CVV 完全同一套验证流程（验证码一次性、10 分钟有效、防爆破锁定）。配套新端点：
  • POST /api/v1/openapi/card/sensitive/send_code —— 发送邮箱/短信验证码并告知需要哪些验证因子（用途固定，同一账户 60 秒冷却，带 Retry-After）。
• 2026-08-03：销卡端点正式收录。POST /api/v1/openapi/card/close —— 不可撤销地注销虚拟卡（异步：受理后 closing(4)，完成以 card.closed webhook 为准；余额经平台审核后退回钱包）。该端点 v1.2 起已上线但此前未收录文档（preview 状态）；v1.3 正式纳入对外契约，行为无变化。
• 2026-08-03：信任窗口（验证一次，窗口内免验证）。二次验证成功后，同一账户在管理员配置的时长内（默认 30 分钟，0=关闭，固定窗口不滑动）再次获取敏感信息无需任何验证字段。send_code 新增响应字段 grace_active，用于探测当前是否需要验证码。非破坏性变更 —— grace_active 为新增字段。

变更

• 管理员开通的敏感访问权语义变为免二次验证特权（面向无人值守 server-to-server 自动化；仍默认关闭、仍需审批）。已开通的凭证行为无任何变化 —— with_sensitive=true 继续免验证码使用。
• 管理员封禁：平台可按卡或按账户维度强制关闭敏感信息获取。封禁同时压制两条授权路径（验证码与免验证特权凭证均无效），返回 403 card_sensitive_access_banned；账户维度封禁同时拦截 /card/sensitive/send_code。
• /card/info 不再返回 403 openapi_sensitive_card_info_disabled。未开通特权的凭证传 with_sensitive=true 但缺验证码时，现在返回 403 + 具体缺失因子的 key（email_code_required / pin_required / 2fa_code_required / sms_code_required）；验证失败/锁定时返回 403 invalid_* / 429。此前匹配 openapi_sensitive_card_info_disabled 的对接方请改为匹配上述 key —— 详见错误码。

v1.2

新增

• 2026-07-07：新增卡片冻结 / 解冻与交易明细端点（4 个）。非破坏性变更——不改动任何已有端点。
  • POST /api/v1/openapi/transactions/list —— 查询名下所有虚拟卡的交易明细
  • POST /api/v1/openapi/card/transactions/list —— 查询单张卡的交易明细
  • POST /api/v1/openapi/card/freeze —— 冻结一张活跃虚拟卡
  • POST /api/v1/openapi/card/unfreeze —— 解冻用户主动冻结的卡
• 交易对象严格脱敏：仅返回 last_four（绝不返回完整 PAN），不含持卡人 PII，不含供应商侧 / 内部订单引用。
• 冻结 / 解冻无需 Idempotency-Key——不涉及资金变动，且被卡状态机保护（重复冻结 → card_already_frozen；重复解冻 → card_not_frozen）。仅用户主动冻结可通过 /card/unfreeze 解冻；风控 / 管理员 / 系统冻结返回 403。

v1.1

新增

• 2026-06-15：/card/apply 通过可选的 first_deposit_amount 支持自定义首充金额，并新增只读的 /card/first_deposit/preview 试算端点。非破坏性变更——first_deposit_amount 可选（空 = 配置底额）；预览是新增端点，不改动任何已有端点。
• 2026-05-26：新增受支持的 card_type 取值 virtual_g（虚拟卡 - G 类）。非破坏性变更——无新增端点、无 schema 变化；未集成 G 卡的客户端不受影响。
• 8 个 OpenAPI endpoint：
  • POST /api/v1/openapi/card_headers/list
  • POST /api/v1/openapi/card_configs/list
  • POST /api/v1/openapi/cards/list
  • POST /api/v1/openapi/card/apply
  • POST /api/v1/openapi/card/first_deposit/preview
  • POST /api/v1/openapi/card/recharge
  • POST /api/v1/openapi/card/info
  • POST /api/v1/openapi/webhook_events/list
• HMAC-SHA256 鉴权（4 个 header）
• 幂等键支持（/card/apply / /card/recharge）
• Webhook 推送：webhook.test / card.opened / card.open_failed / card.recharged / card.recharge_failed / card.closed / card.status_changed
• /card/info 通过 with_sensitive=true 选择性返回完整 PAN / CVV / 到期日 / 持卡人姓名 —— 需凭证被授予该访问权且卡处于 active 状态。默认关闭，开通需审批。

字段封装规则

• 所有对外 ID 是带业务前缀的字符串（card_ / pkg_ / hdr_ / txn_ / evt_），当作不透明 token 使用。
• 资产引用使用 ISO 4217 币种代码 / 资产符号（字符串，不暴露数字 ID）。
• card_type 全小写业务代码（如 virtual_v）。
• 充值 status 用业务码：2 成功 / 3 失败。
• 开卡 / 销卡 webhook status 用字符串：opened / open_failed / closed。
• 内部字段（DB 主键、提供方订单引用、中间计算值、内部标签等）不会通过响应返回。

范围

• 仅虚拟卡：virtual_l / virtual_p / virtual_v / virtual_r / virtual_g
• 不含实体卡 / 转账接口（计划在后续版本）

计划（后续版本）

仅供参考，实际以发版为准

• 独立沙箱环境
• 暴露 GET /openapi.json（自动生成的 OpenAPI 3.0 spec）
• 暴露 GET /openapi.postman.json（自动生成的 Postman Collection）

兼容性承诺

• 同 major 版本（v1.x）内：只新增、不删字段
• 默认值、约束（长度、类型）不会向后不兼容地变
• message_key 一旦发布永久稳定
• 删除字段或改语义会升 major 版本并保留旧版至少 6 个月

反馈

• 邮箱：[email protected]