修改卡片验证码接收手机
POST /openapi/v2/cards/{cardId}/3ds-contact/phone
沿用现有 OpenAPI 签名认证。路径参数 cardId 是卡片查询返回的卡标识,不是完整卡号或数据库主键;仅能操作凭证所属租户的卡片。
请求类型为 application/json,邮箱、手机分别提交。只修改当前卡片的验证码接收地址,不修改登录邮箱、KYC 或其他卡片,不主动发送验证码。提交前须核验持卡人授权和新联系方式归属。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestNo | string | 是 | 1–64 位字母、数字、下划线或连字符,租户内本业务唯一。 |
countryCode | string | 是 | + 后 1–4 位数字。 |
phone | string | 是 | 6–15 位数字,不含区号、空格或分隔符。 |
ownershipVerified | boolean | 是 | 必须为 true;调用方已核验授权与归属的声明,不是平台 OTP 核验。 |
json
{
"requestNo": "contact_phone_001",
"countryCode": "+852",
"phone": "12345678",
"ownershipVerified": true
}修改记录字段
修改接口为响应 data,查询接口为 operations[] 元素。
| 字段 | 类型 | 说明 |
|---|---|---|
operationNo | string | 平台操作编号。 |
requestNo | string | 调用方幂等号。 |
field | string | EMAIL 或 PHONE。 |
targetMasked | string | 脱敏的新联系方式。 |
status | string | UNKNOWN、ACCEPTED、CONFIRMED、FAILED。 |
providerCode | string/null | 渠道安全结果码,可为空。 |
createdAt | string | 创建时间。 |
updatedAt | string | 更新时间。 |
状态与重试
- 外层
code=200表示平台已处理请求,不代表联系方式已生效。 UNKNOWN:可能仍在提交,或结果不确定;ACCEPTED:渠道已受理,尚未确认生效。两者均阻止该卡的其他联系方式修改。CONFIRMED:平台依据外部证据确认已生效;FAILED:明确拒绝,或核实最终未生效。两者允许后续新修改。- 同一
requestNo、相同内容返回原操作;改变内容返回UCARD_REQUEST_CONFLICT。未知结果不得换号绕过,先查询以触发自动核实;持续无法确认时再联系平台,OpenAPI 不提供人工终结接口。 - 不支持修改返回
UCARD_CONTACT_UNSUPPORTED;已有待核实操作返回UCARD_CONTACT_PENDING;参数无效返回UCARD_CONTACT_INVALID。这些标识出现在msg中,不替代外层数字code。
