跳转到内容

查询卡片验证码接收设置 ​

GET /openapi/v1/cards/{cardId}/3ds-contact

沿用现有 OpenAPI 签名认证。路径参数 cardId 是卡片查询返回的卡标识,不是完整卡号或数据库主键;仅能操作凭证所属租户的卡片。

支持修改的卡片返回 EMAIL / PHONE 操作;不支持的卡片返回 deliveryMode=UNSUPPORTED、空操作列表。未确认的联系方式为空,不回退用户账号邮箱。存在待处理修改时,查询会读取渠道当前联系方式,与申请值一致后自动确认原记录;无待处理修改时只查本地。

响应 data ​

字段类型说明
providerNamestring渠道标识,仅作展示,不用于路由或判断能力。
deliveryModestringPROVIDER 渠道维护接收地址;UNSUPPORTED 不支持修改。
emailMaskedstring/null平台已确认的脱敏邮箱。
phoneMaskedstring/null平台已确认的脱敏手机。
versioninteger每次确认修改成功递增。
supportedActionsstring[]可用操作 EMAIL、PHONE,不支持时为空。
pendingboolean是否有尚未终结的修改;为 true 时暂停其他修改。
operationsarray最近 20 条修改记录,结构见下表。

修改记录字段 ​

修改接口为响应 data,查询接口为 operations[] 元素。

字段类型说明
operationNostring平台操作编号。
requestNostring调用方幂等号。
fieldstringEMAIL 或 PHONE。
targetMaskedstring脱敏的新联系方式。
statusstringUNKNOWN、ACCEPTED、CONFIRMED、FAILED。
providerCodestring/null渠道安全结果码,可为空。
createdAtstring创建时间。
updatedAtstring更新时间。

状态与重试 ​

  • 外层 code=200 表示平台已处理请求,不代表联系方式已生效。
  • UNKNOWN:可能仍在提交,或结果不确定;ACCEPTED:渠道已受理,尚未确认生效。两者均阻止该卡的其他联系方式修改。
  • CONFIRMED:平台依据外部证据确认已生效;FAILED:明确拒绝,或核实最终未生效。两者允许后续新修改。
  • 同一 requestNo、相同内容返回原操作;改变内容返回 UCARD_REQUEST_CONFLICT。未知结果不得换号绕过,先查询以触发自动核实;持续无法确认时再联系平台,OpenAPI 不提供人工终结接口。
  • 不支持修改返回 UCARD_CONTACT_UNSUPPORTED;已有待核实操作返回 UCARD_CONTACT_PENDING;参数无效返回 UCARD_CONTACT_INVALID。这些标识出现在 msg 中,不替代外层数字 code。

自动核实 ​

ACCEPTED 可立即核实;UNKNOWN 创建满 120 秒后才核实,以保护仍可能在发送的修改请求。匹配成功后,本次查询返回新的脱敏联系方式、递增的 version 和原操作的 CONFIRMED 状态;无其他待处理修改时 pending=false。

渠道字段缺失、脱敏、值不一致、查询失败或超时时,保留原确认值和待处理状态,可稍后再次查询。超时本身不代表修改失败。每次符合条件的查询至多发起一次只读请求,最长等待 10 秒,不会重发联系方式修改。确认设置生效不代表真实验证码已送达。