跳到主要内容

KYC 发卡流程

适用场景：目标卡产品的 kyc_level 为 Standard / Enhanced，或 cardholder_required_fields 中要求 identity、billing_address、kyc_verification 等字段。若产品仅要求 Simplified 字段，可沿用基础持卡人创建流程，无需本指南全部步骤。

警告：仅当持卡人 status 为 SUCCESS 时才能发起开卡。
持卡人处于 PENDING 或 FAILED 时，请勿调用创建卡片；须先完成平台审批或处理驳回。

警告：开卡受地区与国籍限制。
持卡人的账单地址国家、国籍、手机区号须满足目标产品的 support_billing_region、support_nationality / sanctioned_nationality、support_area_code。建议在创建持卡人并完成 KYC 之前，先查看产品列表中的限制字段，避免 KYC 通过后仍无法开卡。

持卡人要求

  • 以目标产品的 cardholder_required_fields 为准；仅 required: true 的字段必须提供。
  • 地址字段字符集：字母、数字、空格及 , . ' / # ( ) - &；postcode 长度 4–10。
  • 美国国籍持卡人需提供 9 位数字 ssn（以产品必填配置为准）。

概览​

前置条件：获取 Access Token​

所有业务接口需在请求头携带：

Header说明
AuthorizationBearer {access_token}（获取 token 接口除外）
X-Request-Id请求 ID，建议 UUID；写操作同时用于幂等
curl -X POST "https://{host}/api/open/v1/auth/token" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "api_key": "{your_api_key}",
    "api_secret": "{your_api_secret}"
  }'
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}

后续示例中的 {token} 均指上述 access_token。

步骤 1：检查产品要求​

调用卡产品列表，确认目标产品的 KYC 等级、必填字段与地区限制。

curl -X GET "https://{host}/api/open/v1/issuing/products" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}"

响应中每个产品的 id 即为后续开卡 / 预校验使用的 card_product_id（账户–产品绑定 ID）。

重点关注：

字段说明
kyc_levelSimplified / Standard / Enhanced
cardholder_required_fields持卡人必填字段树（含嵌套 fields）
support_billing_region账单地址国家白名单；空表示不限制
support_nationality / sanctioned_nationality国籍白/黑名单；空表示不限制
support_area_code手机区号白名单；空表示不限制
min_open_card_amount / min_recharge_amount开卡与充值门槛
max_cards_per_cardholder持卡人最大开卡数；空表示不限制

Enhanced 类产品的 cardholder_required_fields 通常会包含 identity、billing_address（或 residential_address）、kyc_verification 等。示例（字段以实际产品配置为准）：

{
  "id": "acct-prod-xxxxx",
  "name": "Personal Visa Enhanced",
  "status": "ENABLED",
  "kyc_level": "Enhanced",
  "model_type": "SINGLE",
  "card_scheme": "VISA",
  "country": "SG",
  "support_billing_region": ["SG", "HK"],
  "support_nationality": ["SG", "HK", "CN"],
  "sanctioned_nationality": [],
  "support_area_code": ["+65", "+852"],
  "cardholder_required_fields": [
    { "name": "first_name", "type": "string", "required": true },
    { "name": "last_name", "type": "string", "required": true },
    { "name": "email", "type": "string", "required": true },
    { "name": "birth_date", "type": "string", "required": true },
    { "name": "nationality", "type": "string", "required": true },
    {
      "name": "identity",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "type", "type": "string", "required": true },
        { "name": "number", "type": "string", "required": true },
        { "name": "issue_country", "type": "string", "required": true },
        { "name": "front_file_id", "type": "string", "required": true },
        { "name": "back_file_id", "type": "string", "required": false }
      ]
    },
    {
      "name": "billing_address",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "country", "type": "string", "required": true },
        { "name": "state", "type": "string", "required": true },
        { "name": "city", "type": "string", "required": true },
        { "name": "line1", "type": "string", "required": true },
        { "name": "postcode", "type": "string", "required": true }
      ]
    },
    {
      "name": "kyc_verification",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "method", "type": "string", "required": true }
      ]
    }
  ]
}

只有标注 "required": true 的字段是必填；可选字段可省略。开卡前也可用步骤 2.5 的预校验接口提前检查。

城市名称建议先查询公共城市列表：

curl -X GET "https://{host}/api/open/v1/common/cities?country=SG" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}"

步骤 2：上传证件图片​

证件图片均须先上传获取 file_id。

curl -X POST "https://{host}/api/open/v1/common/files/upload" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}" \
  -F "file=@/path/to/passport_front.jpg"
{
  "success": true,
  "data": {
    "file_id": "file_xxxxxxxx",
    "file_name": "passport_front.jpg",
    "file_type": "image/jpeg",
    "size": 204800
  }
}

限制：最大 10MB；格式 jpg / jpeg / png / pdf。

下载：GET /api/open/v1/common/files/{id}。

步骤 2.5（可选）：持卡人 × 产品预校验​

在正式创建持卡人之前，可用草稿字段或已有 cardholder_id 做预校验，减少开卡时的 CARDHOLDER_FIELDS_INCOMPLETE。

curl -X POST "https://{host}/api/open/v2/issuing/cardholders/validate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}" \
  -d '{
    "card_product_id": "acct-prod-xxxxx",
    "email": "sarah.chen@example.com",
    "first_name": "Sarah",
    "last_name": "Chen",
    "birth_date": "1992-06-15",
    "nationality": "SG",
    "area_code": "+65",
    "billing_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "line1": "9 N Buona Vista Dr",
      "postcode": "138666"
    }
  }'
  • 传入 cardholder_id 时优先生效，可少传草稿字段。
  • 不传 card_product_id 时，校验账户下全部 ENABLED 产品。
  • 关注响应中的 valid、issues[].type（MISSING_FIELDS / COUNTRY_RESTRICTION）与 missing_fields。

步骤 3：使用 KYC 字段创建持卡人（v2）​

POST /api/open/v2/issuing/cardholders

KYC 验证方式二选一：

方式适用场景结果
REDIRECT_LINK希望由平台通过 Sumsub 完成 IDV获取验证链接，引导持卡人完成验证
THIRD_PARTY商户已通过自有 KYC 服务商完成验证提交服务商 reference_id

创建持卡人时指定 method，无需 kyc_proof：

curl -X POST "https://{host}/api/open/v2/issuing/cardholders" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@example.com",
    "birth_date": "1992-06-15",
    "gender": 2,
    "mobile_number": "90755646",
    "mobile_country": "SG",
    "area_code": "+65",
    "nationality": "SG",
    "identity": {
      "type": "PASSPORT",
      "number": "E98765432",
      "issue_country": "SG",
      "issue_date": "2018-01-15",
      "expiry_date": "2028-01-14",
      "front_file_id": "file_xxxxxxxx"
    },
    "billing_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "district": "Buona Vista",
      "line1": "9 N Buona Vista Dr",
      "line2": "THE METROPOLIS",
      "postcode": "138666"
    },
    "delivery_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "line1": "9 N Buona Vista Dr",
      "postcode": "138666"
    },
    "kyc_verification": {
      "method": "REDIRECT_LINK"
    }
  }'
{
  "success": true,
  "data": {
    "id": "ch_9d6017b2-0c2f-4b2e-876b-992b0db9597d"
  }
}

接着获取 KYC 链接（须已设置 REDIRECT_LINK）：

curl -X POST "https://{host}/api/open/v1/issuing/cardholders/{id}/kycLink" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}"
{
  "success": true,
  "data": {
    "url": "https://in.sumsub.com/websdk/p/...",
    "expires_at": "2026-04-04 17:32:50",
    "review_status": "init"
  }
}

将持卡人重定向到 url 完成身份验证，并订阅 Webhook（见步骤 4）。也可通过 GET /api/open/v2/issuing/cardholders/{id} 查看 kyc_status 与 kyc_verification.url。

证件类型 type 支持：ID_CARD、PASSPORT、HK_HKID、DLN。非护照创建时通常需提供 back_file_id。

方式 B：THIRD_PARTY​

若已通过自有 KYC 服务商完成验证，提交 kyc_proof。

curl -X POST "https://{host}/api/open/v2/issuing/cardholders" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@example.com",
    "birth_date": "1992-06-15",
    "mobile_number": "90755646",
    "mobile_country": "SG",
    "area_code": "+65",
    "nationality": "SG",
    "identity": {
      "type": "PASSPORT",
      "number": "E98765432",
      "issue_country": "SG",
      "front_file_id": "file_xxxxxxxx"
    },
    "billing_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "line1": "9 N Buona Vista Dr",
      "postcode": "138666"
    },
    "kyc_verification": {
      "method": "THIRD_PARTY",
      "kyc_proof": {
        "provider": "YOUR_PROVIDER",
        "reference_id": "your_provider_ref_1234567890",
        "documents": [
          {
            "file_id": "file_idv_report",
            "report_type": "IDV"
          }
        ]
      }
    }
  }'

kyc_proof.reference_id：长度 10–128，且全局唯一。重复会返回 CARDHOLDER_KYC_REFERENCE_ALREADY_EXISTS。

创建成功后仍可能需等待平台对持卡人的审批（status → SUCCESS）。THIRD_PARTY 场景下，若上游 IDV 尚未最终通过，后续开卡可能进入异步等待（见步骤 5）。

步骤 4：等待 KYC / 持卡人可用​

状态说明​

字段取值说明
statusPENDING / SUCCESS / FAILED平台持卡人审批状态；开卡要求 SUCCESS
kyc_statusNOT_STARTED / PENDING / VERIFIED / REJECTEDKYC 进度；产品要求 KYC 时通常需 VERIFIED

Webhook​

建议订阅：

  • cardholder.created
  • cardholder.updated
  • cardholder.kyc.status_changed

cardholder.kyc.status_changed 的 data 示意：

{
  "cardholder_id": "ch_9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "status": "SUCCESS",
  "kyc_status": "VERIFIED",
  "first_name": "Sarah",
  "last_name": "Chen",
  "email": "sarah.chen@example.com",
  "create_time": "...",
  "update_time": "...",
  "kyc_verification_url": "https://...",
  "kyc_verification_url_expires_at": "..."
}

kyc_verification_url 仅在 REDIRECT_LINK 且链接仍有效时可能出现。

REDIRECT_LINK 未完成 Sumsub（未达到 VERIFIED）时，不能开卡，会返回 CARDHOLDER_KYC_NOT_COMPLETE，且不支持延后开卡（无 WAITING_KYC）。
KYC 被拒绝时返回 CARDHOLDER_KYC_REJECTED。

步骤 5：创建卡片​

当 status = SUCCESS，且产品要求的 KYC 已满足（通常 kyc_status = VERIFIED）后，调用 v2 开卡：

curl -X POST "https://{host}/api/open/v2/issuing/cards" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -H "X-Request-Id: {uuid}" \
  -d '{
    "cardholder_id": "ch_9d6017b2-0c2f-4b2e-876b-992b0db9597d",
    "card_product_id": "acct-prod-xxxxx",
    "label": "Sarah travel",
    "recharge_amount": 100,
    "out_id": "merchant-order-001"
  }'
{
  "success": true,
  "data": {
    "id": "card_d26f2287-434b-41a4-af47-f06dbf6f9e71"
  }
}
  • card_product_id：步骤 1 产品列表中的 id（必填）。
  • recharge_amount：允许为 0；须满足产品 min_open_card_amount / min_recharge_amount。
  • out_id：可选外部标识，便于对账。

错误处理​

建卡时资料不全​

{
  "success": false,
  "code": "CARDHOLDER_FIELDS_INCOMPLETE",
  "message": "...",
  "data": {
    "missing_fields": [
      {
        "name": "billing_address",
        "type": "object",
        "required": true,
        "fields": [
          { "name": "country", "type": "string", "required": true }
        ]
      }
    ]
  }
}

处理建议：

  1. 调用 PUT /api/open/v2/issuing/cardholders 补齐缺失字段后重试开卡；或
  2. 先用 POST .../cardholders/validate 对照目标产品检查草稿/现有持卡人。

持卡人状态不可用​

情况错误码（示例）
status 非 SUCCESSCARDHOLDER_STATUS_NOT_ACTIVE
KYC 未完成（尤其 REDIRECT_LINK）CARDHOLDER_KYC_NOT_COMPLETE
KYC 已拒绝CARDHOLDER_KYC_REJECTED

请等待审批 / KYC Webhook，或按驳回原因更新资料后重试。

地区与国籍限制​

错误码含义
CARDHOLDER_BILLING_COUNTRY_NOT_ALLOWED账单国家不在白名单
CARDHOLDER_NATIONALITY_SANCTIONED国籍在制裁/黑名单
CARDHOLDER_NATIONALITY_NOT_SUPPORTED国籍不在支持列表
CARDHOLDER_AREA_CODE_NOT_SUPPORTED区号不支持

开卡前请对照产品列表中的限制字段，必要时更换产品或更换持卡人资料。

推荐检查清单​

  1. 已获取 token，请求头含 Authorization 与 X-Request-Id
  2. 已读取目标产品的 cardholder_required_fields 与地区/国籍限制
  3. 证件图片已上传，拿到 file_id
  4. （可选）/cardholders/validate 通过
  5. 已用 v2 创建持卡人并提交正确的 kyc_verification.method
  6. REDIRECT_LINK：已引导用户完成 Sumsub，且 kyc_status = VERIFIED
  7. status = SUCCESS
  8. POST /v2/issuing/cards 传入正确的 card_product_id
  9. 已处理 CARDHOLDER_FIELDS_INCOMPLETE / KYC / 地区类错误

相关接口速查​

能力方法与路径
获取 TokenPOST /api/open/v1/auth/token
卡产品列表GET /api/open/v1/issuing/products
城市列表GET /api/open/v1/common/cities
文件上传 / 下载POST /api/open/v1/common/files/upload、GET /api/open/v1/common/files/{id}
创建 / 更新 / 详情持卡人 v2POST /api/open/v2/issuing/cardholders、PUT /api/open/v2/issuing/cardholders、GET /api/open/v2/issuing/cardholders/{id}
持卡人预校验POST /api/open/v2/issuing/cardholders/validate
获取 KYC 链接POST /api/open/v1/issuing/cardholders/{id}/kycLink
创建卡片 v2POST /api/open/v2/issuing/cards
发卡余额（可选）GET /api/open/v1/account/issuing/balance