Z Zise Developers
/
账户中心 › API 参考 › 实名

直接更新会员 KYC 资料（部分更新）

PATCH /v1/kyc scope: kyc:write
商户自身 需 x-idempotency-key

商户服务端直接传 JSON 更新会员的主实名档案，无需托管页面。可修改姓名、性别、生日、邮箱、电话、证件类型与有效期、照片、居住类型及地址等资料。identity_number（证件号码）、nationality（国籍）、identity_issue_country（证件签发国家）、address_country（居住国家）不可修改；传入即返回invalid_fields，整次更新不生效。只传 profile 中要修改的字段；未传的资料和证件照片保持原值。传空字符串或空数组属于显式修改，仍须通过字段校验；null 不代表保持原值。identity_photos 也按子字段合并，residence_permit_urls 则整组替换。空 profile、未知字段、非法手机号或字段类型错误会被拒绝。

更新成功返回 pending、level: 0，资料重新进入审核；各卡产品的 KYC记录同步退回待审。复审通过前，要求实名等级的业务不可继续。该接口不直接更新已存在的卡或上游持卡人的联系资料，也不会自动重试失败开卡单。若本次开卡因手机号占用失败，改成用户真实可用号码、复审通过后，用新的幂等键重新发起开卡。复用旧开卡幂等键会返回原失败结果。

不允许修改审核状态、实名等级、会员归属或快捷 KYC 资料池。修改 profile.email 不会更改账号登录邮箱；新联系邮箱需匹配账号邮箱，或携带匹配的 email_verify_key。未建档返回 not_found，不自动建档。并发修改返回 state_invalid，使用新的幂等键重新提交。

字段类型必填说明
x-on-behalf-of string 必填 会员的 external_member_id 或 mem_<uuid>，不是开卡申请 ID。
x-idempotency-key string 必填

请求体

字段类型必填说明
email_verify_key string 可选 修改为新的联系邮箱时使用的邮箱验证凭据。
profile object 必填
profile.first_name string 可选
profile.last_name string 可选
profile.email string 可选
profile.phone string 可选
profile.phone_zone_number string 可选
profile.identity_type string 可选
profile.identity_expiry_date string 可选
profile.cardholder_residence string 可选
profile.residence_permit_type string 可选
profile.sex string 可选
profile.occupation string 可选
profile.birth_date string 可选
profile.address_province string 可选
profile.address_city string 可选
profile.address_district string 可选
profile.address string 可选
profile.street_number string 可选
profile.postal_code string 可选
profile.identity_photos object 可选
profile.residence_permit_urls string[] 可选

响应

200已更新并进入待审核，响应不回显实名资料或影像。
{
  "kyc_id": "48",
  "status": "pending",
  "review_status": "UNREVIEWED",
  "level": 0
}
400invalid_request · invalid_fields · member_context_required · state_invalid · request_rejected · idempotency_key_required
401invalid_token · invalid_signature · signature_required
403insufficient_scope
404member_not_found · not_found
409idempotency_key_reused
请求 
curl -X PATCH 'https://api.zinfra.vip/v1/kyc' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "profile": {
      "first_name": "Alex",
      "occupation": "designer",
      "address": "25 Main Street",
      "phone_zone_number": "1",
      "phone": "2025550123"
    }
  }'
const res = await fetch("https://api.zinfra.vip/v1/kyc", {
  method: "PATCH",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "profile": {
      "first_name": "Alex",
      "occupation": "designer",
      "address": "25 Main Street",
      "phone_zone_number": "1",
      "phone": "2025550123"
    }
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.patch(
    "https://api.zinfra.vip/v1/kyc",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "profile": {
        "first_name": "Alex",
        "occupation": "designer",
        "address": "25 Main Street",
        "phone_zone_number": "1",
        "phone": "2025550123"
      }
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("PATCH", "https://api.zinfra.vip/v1/kyc",
    strings.NewReader(`{
  "profile": {
    "first_name": "Alex",
    "occupation": "designer",
    "address": "25 Main Street",
    "phone_zone_number": "1",
    "phone": "2025550123"
  }
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/kyc"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("""
{
  "profile": {
    "first_name": "Alex",
    "occupation": "designer",
    "address": "25 Main Street",
    "phone_zone_number": "1",
    "phone": "2025550123"
  }
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zinfra.vip/v1/kyc');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "profile": {
    "first_name": "Alex",
    "occupation": "designer",
    "address": "25 Main Street",
    "phone_zone_number": "1",
    "phone": "2025550123"
  }
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "kyc_id": "48",
  "status": "pending",
  "review_status": "UNREVIEWED",
  "level": 0
}