跳转到主要内容

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.

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

​
步骤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卡片消费上限。BIN 527735、555071、555243 必填（必须 ≥ 0.01）。其他 BIN 可选（省略时默认为 0；传入时必须 ≥ 0）。
spending_controls单笔消费限额 —— 参见 消费限额
risk_controls配置 3DS 行为（enable_3ds、allow_3ds_transactions）—— 参见 3D Secure
metadata键值对形式的自定义元信息（最多 3200 字节）
usage_typeNORMAL（默认）或 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": "[email protected]",
      "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 接口。