跳转到主要内容
本指南将引导你在沙盒环境中签发一张虚拟卡。完成之后，你将拥有一位持卡人和一张已激活的虚拟卡，可用于模拟交易。
前置条件
  • 已启用 Card Issuance 的 UQPAY 沙盒账户
  • 通过 Access Token 接口获取的 API Token
  • 已安装 UQPAY CLI（推荐），或 curl
1

创建持卡人

持卡人代表将使用这张卡的人。用姓名、邮箱、手机号和国家代码创建一个持卡人。
uqpay issuing cardholder create \
  -d first_name=Alex \
  -d last_name=Chen \
  -d [email protected] \
  -d country_code=SG \
  -d phone_number=91234567
响应：
{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}
保存 cardholder_id —— 创建卡片时需要用到它。
某些卡产品需要 Enhanced KYC。如果 cardholder_status 返回 PENDING，持卡人需要先完成身份验证才能签发卡片。参见 KYC 验证。
2

查找卡产品

卡产品定义了 BIN、卡组织、资金模式和支持的币种。列出你账户下可用的卡产品。
uqpay issuing product list
找一个 card_form 包含 VIR（虚拟）的卡产品。沙盒模拟场景下，使用 BIN 为 40963608 的卡产品 —— 这是唯一支持 Simulate Authorization 接口的 BIN。卡产品示例（节选）：
{
  "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，下一步会用到。
3

创建一张虚拟卡

使用你选中的卡产品，为持卡人签发一张虚拟卡。
uqpay issuing card create \
  -d cardholder_id=25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -d card_product_id=467e993f-317a-49fc-9ea0-bf49de7d1f76 \
  -d card_currency=USD \
  -d 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.create.succeeded webhook。虚拟卡不需要激活。
4

验证卡片

查询卡片，确认它已激活。
uqpay issuing card list \
  --cardholder-id 25ea804d-7fd5-43d5-8792-0fc0214cdb2f
响应：
{
  "total_items": 1,
  "total_pages": 1,
  "data": [
    {
      "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
      "card_bin": "40963608",
      "card_number": "40963608****1764",
      "card_scheme": "VISA",
      "card_status": "ACTIVE",
      "card_currency": "USD",
      "card_limit": "1000.00",
      "available_balance": "1000.00",
      "consumed_amount": "0.00",
      "form_factor": "VIRTUAL",
      "mode_type": "SHARE",
      "cardholder": {
        "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
        "first_name": "Alex",
        "last_name": "Chen",
        "email": "[email protected]",
        "cardholder_status": "SUCCESS",
        "create_time": "2026-04-10T18:03:47+08:00"
      },
      "create_time": "2026-04-10T18:04:44+08:00"
    }
  ]
}
卡片状态为 ACTIVE，可用余额为 1000.00 USD。可以用于模拟交易。

​
下一步

模拟交易

使用 Simulator API 测试授权和冲正流程。

核心概念

了解卡形态、资金模式和配置选项。

消费限额

设置单笔限额和商户类别限制。

卡生命周期

冻结、解除冻结或注销卡片。