跳转到内容

修改卡片验证码接收手机 ​

POST /openapi/v1/cards/{cardId}/3ds-contact/phone

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

请求类型为 application/json,邮箱、手机分别提交。只修改当前卡片的验证码接收地址,不修改登录邮箱、KYC 或其他卡片,不主动发送验证码。提交前须核验持卡人授权和新联系方式归属。

请求体 ​

字段类型必填说明
requestNostring是1–64 位字母、数字、下划线或连字符,租户内本业务唯一。
countryCodestring是+ 后 1–4 位数字。
phonestring是6–15 位数字,不含区号、空格或分隔符。
ownershipVerifiedboolean是必须为 true;调用方已核验授权与归属的声明,不是平台 OTP 核验。
json
{
  "requestNo": "contact_phone_001",
  "countryCode": "+852",
  "phone": "12345678",
  "ownershipVerified": true
}

修改记录字段 ​

修改接口为响应 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。