签发虚拟卡

虚拟卡即时创建，可以立即用于线上交易 —— 无需激活。每张虚拟卡都包含 PAN、过期日期和 CVV。

前置条件

一位 cardholder_status 为 SUCCESS 的持卡人 —— 参见创建持卡人
如果使用 Single mode 产品，发卡账户余额需充足 —— 参见为发卡账户余额充值

步骤1：选择卡产品

列出你账户下可用的卡产品，找一个 card_form 包含 VIR 的产品。

curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_number=1&page_size=10" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

{
  "total_items": 2,
  "total_pages": 1,
  "data": [
    {
      "product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
      "card_bin": "40963608",
      "card_scheme": "VISA",
      "mode_type": "SHARE",
      "card_form": ["VIR", "PHY"],
      "card_currency": ["USD", "SGD"],
      "product_status": "ENABLED"
    }
  ]
}

保存你要使用的产品的 product_id。

使用 Simulator 测试时，选择 BIN 为 40963608 的产品。

步骤2：创建卡片

调用 Create Card 接口，传入持卡人 ID、产品 ID、币种和卡限额。

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": 1000
  }'

响应：

{
  "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
  "card_order_id": "79224316-ecad-4e61-9eeb-e7929bda124c",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-10T18:04:44+08:00"
}

卡片初始状态为 PENDING，几秒后变为 ACTIVE。

可选参数

参数	说明
`card_limit`	卡片消费上限。Business Mastercard 和 Personal Visa 必填（必须 ≥ 0.01）；Business Visa 可选（省略时默认为 0；传入时必须 ≥ 0）。参见卡产品确认你的产品类型。
`spending_controls`	单笔消费限额 —— 参见消费限额
`risk_controls`	配置 3DS 行为（`enable_3ds`、`allow_3ds_transactions`）—— 参见 3D Secure
`metadata`	键值对形式的自定义元信息（最多 3200 字节）
`card_art_id`	应用于新卡的卡面 —— 参见卡面。省略时使用账户默认卡面。
`usage_type`	`NORMAL`（默认）或 `ONE_TIME`（一次性卡）
`auto_cancel_trigger`	仅 `ONE_TIME` 卡支持：`ON_AUTH` 或 `ON_CAPTURE`

步骤3：接收 webhook

处理完成后，UQPAY 会发送 card.create.succeeded 或 card.create.failed webhook。在 webhook 配置中订阅这些事件。 示例：card.create.succeeded

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.create.succeeded",
  "event_id": "8d62450e-11cd-4e62-b774-bbb52ac959df",
  "source_id": "79224316-ecad-4e61-9eeb-e7929bda124c",
  "data": {
    "card_available_balance": "1000",
    "card_bin": "40963608",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_scheme": "VISA",
    "card_status": "ACTIVE",
    "cardholder": {
      "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
      "cardholder_status": "SUCCESS",
      "create_time": "2026-04-10T18:03:47+08:00",
      "email": "quickstart-1775815424@example.com",
      "first_name": "Alex",
      "last_name": "Chen"
    },
    "form_factor": "VIRTUAL",
    "metadata": {},
    "mode_type": "SHARE",
    "risk_control": {
      "enable_3ds": "Y",
      "allow_3ds_transactions": "Y"
    },
    "spending_limits": [
      {
        "amount": "20000",
        "interval": "PER_TRANSACTION"
      }
    ]
  }
}

步骤4：查询卡片敏感信息

向持卡人展示完整卡号、过期日期和 CVV 时，使用安全卡片展示（iframe）集成方案，避免在你的后端暴露敏感卡数据。如果你的系统已通过 PCI DSS 合规认证，也可以使用 Retrieve Sensitive Card Details 接口。

核心概念 —— 卡形态、卡模式与卡设置
签发实体卡 —— 绑定并激活实体卡
卡生命周期 —— 冻结、解除冻结或注销卡片
Card Created webhook
Create Card API

入门

持卡人

卡片

充值

管理与安全

集成

参考

步骤1：选择卡产品

步骤2：创建卡片

可选参数

步骤3：接收 webhook

步骤4：查询卡片敏感信息

​步骤1：选择卡产品

​步骤2：创建卡片

​可选参数

​步骤3：接收 webhook

​步骤4：查询卡片敏感信息

​相关阅读

步骤1：选择卡产品

步骤2：创建卡片

可选参数

步骤3：接收 webhook

步骤4：查询卡片敏感信息

相关阅读