跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

部分卡产品（按 BIN 区分）要求持卡人先完成 Enhanced KYC —— 即通过第三方服务商完成身份验证 —— 才能签发卡片。本指南涵盖从检查产品要求到成功签发卡片的完整流程。
如果你的卡产品只需要基础字段（Simplified KYC），现有的持卡人创建流程可以照常使用，无需改动。通过 List Products 查询产品要求的字段。

​
概览

​
前置条件

调用 API 之前，先获取 Access Token： 
curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/connect/token" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {your_api_key}" \
  -H "x-client-id: {your_client_id}"

{
  "auth_token": "eyJhbGciOiJIUzI1NiIs...",
  "expired_at": 1775210493
}
后续所有请求都通过 x-auth-token 请求头传入返回的 auth_token。

​
步骤1：检查产品要求

调用 List Products 查看目标产品要求哪些字段。 
curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_size=10&page_number=1" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}"
查看响应中的 required_fields 数组。Enhanced KYC 产品的必填字段会包含 identity、residential_address 和 kyc_verification。以下是一个 Enhanced 产品的示例（BIN 46651711）： 
{
  "product_id": "0d8f10de-c888-4107-ab65-1cc9deb31b3b",
  "card_bin": "46651711",
  "card_scheme": "VISA",
  "card_form": ["VIR"],
  "card_currency": ["USD", "SGD", "HKD"],
  "mode_type": "SHARE",
  "kyc_level": "ENHANCED",
  "max_card_quota": 3001,
  "product_status": "ENABLED",
  "required_fields": [
    { "name": "first_name", "type": "string", "required": true },
    { "name": "last_name", "type": "string", "required": true },
    { "name": "email", "type": "string", "required": true },
    { "name": "country_code", "type": "string", "required": true },
    { "name": "date_of_birth", "type": "string", "required": true },
    { "name": "phone_number", "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": "front_file", "type": "string", "required": true },
        { "name": "back_file", "type": "string", "required": false },
        { "name": "hand_file", "type": "string", "required": false }
      ]
    },
    {
      "name": "residential_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": "district", "type": "string", "required": false },
        { "name": "line1", "type": "string", "required": true },
        { "name": "line2", "type": "string", "required": false },
        { "name": "line_en", "type": "string", "required": true },
        { "name": "postal_code", "type": "string", "required": true }
      ]
    },
    {
      "name": "kyc_verification",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "method", "type": "string", "required": true },
        {
          "name": "kyc_proof",
          "type": "object",
          "required": false,
          "fields": [
            { "name": "provider", "type": "string", "required": false },
            { "name": "reference_id", "type": "string", "required": false }
          ]
        }
      ]
    }
  ]
}
required_fields 告诉你具体需要哪些信息。只有标注 "required": true 的字段是必填的 —— 可选字段可以省略。

​
步骤2：使用 Enhanced KYC 创建持卡人

调用 Create Cardholder，传入完整的必填字段以及 kyc_verification。
residential_address.country 和 nationality 字段受地区限制约束。支持的国家和受制裁的国籍清单参见 持卡人地区限制。
共有两种验证方式，根据你的场景选择：
方式适用场景结果
SUMSUB_REDIRECT希望由 UQPAY 通过 Sumsub 处理 IDV返回 IDV URL，供持卡人完成验证
THIRD_PARTY你已通过自有 KYC 服务商完成持卡人验证持卡人立即完成验证

​
方式 A：SUMSUB_REDIRECT

如果你希望 UQPAY 通过 Sumsub 处理身份验证，使用此方式。你会收到一个 IDV URL 用于重定向持卡人。 
curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}" \
  -H "x-idempotency-key: cc58fa96-7a49-4be1-a70b-85075c1b4957" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "[email protected]",
    "country_code": "SG",
    "phone_number": "90755646",
    "date_of_birth": "1992-06-15",
    "nationality": "SG",
    "identity": {
      "type": "PASSPORT",
      "number": "E98765432",
      "front_file": "<base64_encoded_image>",
      "back_file": "<base64_encoded_image>",
      "hand_file": "<base64_encoded_image>"
    },
    "residential_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "district": "Buona Vista",
      "line1": "9 N Buona Vista Dr",
      "line2": "THE METROPOLIS",
      "line_en": "9 N Buona Vista Dr, THE METROPOLIS",
      "postal_code": "138666"
    },
    "kyc_verification": {
      "method": "SUMSUB_REDIRECT"
    }
  }'
响应 —— 持卡人进入 INCOMPLETE 状态，并附带一个 IDV 链接： 
{
  "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "cardholder_status": "INCOMPLETE",
  "idv_verification_url": "https://in.sumsub.com/websdk/p/sbx_MVSJTHTZj77PZggH",
  "idv_url_expires_at": "2026-04-04T17:32:50+08:00"
}
将持卡人重定向到 idv_verification_url 完成身份验证，然后等待 webhook 通知（见步骤3）。

​
方式 B：THIRD_PARTY

如果你已通过自有 KYC 服务商完成持卡人身份验证并有凭证引用，使用此方式。 
curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}" \
  -H "x-idempotency-key: {unique_uuid}" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "[email protected]",
    "country_code": "SG",
    "phone_number": "90755646",
    "date_of_birth": "1992-06-15",
    "nationality": "SG",
    "identity": {
      "type": "PASSPORT",
      "number": "E98765432",
      "front_file": "<base64_encoded_image>",
      "back_file": "<base64_encoded_image>",
      "hand_file": "<base64_encoded_image>"
    },
    "residential_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "district": "Buona Vista",
      "line1": "9 N Buona Vista Dr",
      "line2": "THE METROPOLIS",
      "line_en": "9 N Buona Vista Dr, THE METROPOLIS",
      "postal_code": "138666"
    },
    "kyc_verification": {
      "method": "THIRD_PARTY",
      "kyc_proof": {
        "provider": "YOUR_PROVIDER",
        "reference_id": "your_provider_ref_1234567890"
      }
    }
  }'
kyc_proof.reference_id 至少 10 个字符，全局唯一。
响应 —— 持卡人立即完成验证： 
{
  "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "cardholder_status": "SUCCESS"
}
可以直接进入步骤4：创建卡片。

​
步骤3：等待 KYC 审核通过（仅 SUMSUB_REDIRECT）

如果你使用了 SUMSUB_REDIRECT，订阅 cardholder.kyc.status_changed webhook 以实时接收 KYC 状态变更。 Webhook payload 示例（KYC 已通过）： 
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "cardholder.kyc.status_changed",
  "event_id": "d92ab1ec-1737-4b3c-bedb-7500a3c02677",
  "source_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "data": {
    "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
    "cardholder_status": "SUCCESS",
    "country_code": "SG",
    "create_time": "2026-04-03T17:32:50+08:00",
    "date_of_birth": "1992-06-15",
    "email": "[email protected]",
    "first_name": "Sarah",
    "idv_provider": "SUMSUB",
    "idv_status": "PASSED",
    "last_name": "Chen",
    "nationality": "SG",
    "phone_number": "90755646",
    "update_time": "2026-04-03T17:34:49+08:00"
  }
}
当 cardholder_status 变为 SUCCESS 时，持卡人即可签发卡片。
持卡人处于 PENDING 状态时无法签发卡片。请先等待 KYC 审核通过。

​
步骤4：创建卡片

当 cardholder_status 为 SUCCESS 后，调用 Create Card： 
curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}" \
  -H "x-idempotency-key: bf705cbd-27f0-48d1-a60b-212134a89ad7" \
  -d '{
    "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
    "card_product_id": "0d8f10de-c888-4107-ab65-1cc9deb31b3b",
    "card_currency": "USD",
    "card_limit": 1000
  }'
响应： 
{
  "card_id": "d26f2287-434b-41a4-af47-f06dbf6f9e71",
  "card_order_id": "c004375c-8137-4b94-b948-4282bff33625",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-03T17:35:55+08:00",
  "risk_controls": {}
}

​
错误处理

​
建卡时 KYC 信息不足

如果持卡人尚未满足产品的 KYC 要求就尝试创建卡片，你会收到如下错误，其中 missing_fields 指明仍需补齐的字段： 
{
  "code": "kyc_insufficient",
  "message": "Cardholder KYC information is insufficient for this product.",
  "missing_fields": ["identity", "residential_address"]
}
你可以选择：
  1. 先通过 Update Cardholder 更新持卡人信息，然后重试建卡。
  2. 在 Create Card 请求中通过 cardholder_required_fields 字段内联补充缺失的信息。

​
持卡人处于 PENDING 状态

持卡人 cardholder_status 为 PENDING 时创建卡片会被拒绝。请等待 KYC 审核完成后再重试。