3D Secure

UQPAY 支持 3D Secure（3DS）身份验证，帮助防范线上交易欺诈。risk_controls 下有两个独立字段控制 3DS 行为：

enable_3ds —— 卡片是否注册 3DS。
allow_3ds_transactions —— 注册 3DS 之后，持卡人是否需要完成挑战（如 OTP），还是走无摩擦流程。

不同卡产品对 3DS 配置的支持有所不同。参见卡产品。

两字段交互逻辑

`enable_3ds`	`allow_3ds_transactions`	行为
`N`	（任意）	完全跳过 3DS。线上交易不进入 3DS 身份验证。
`Y`	`Y`	持卡人可能被挑战（OTP）。
`Y`	`N`	走无摩擦流程 —— 不需要 OTP，交易被视为持卡人已验证。

allow_3ds_transactions 仅在 enable_3ds 为 Y 时生效。当 enable_3ds 为 N 时，无论 allow_3ds_transactions 取值如何，卡片都会跳过 3DS。

配置 `enable_3ds`

控制卡片是否注册 3DS。仅 Business Visa 和 Personal Visa 支持。卡片处于 PENDING 或 ACTIVE 状态时可修改。

创建卡片时设置

{
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_currency": "USD",
  "card_limit": 2100.02,
  "risk_controls": {
    "enable_3ds": "N"
  }
}

对已有卡片更新

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_controls": {
      "enable_3ds": "N"
    }
  }'

enable_3ds 仅在卡片显式设置过该字段时返回。未设置时，卡片继承 Account 级 3DS 配置。
enable_3ds 仅 Business Visa 和 Personal Visa 支持；Business Mastercard 会忽略。
如要注册 3DS 但跳过挑战流程，将 enable_3ds 设为 Y、allow_3ds_transactions 设为 N。

当 enable_3ds 为 N 时，卡片完全跳过 3DS 身份验证。此类交易无法以欺诈或未授权使用为由发起争议。

配置 `allow_3ds_transactions`

取值	行为
`Y`（默认）	风控引擎评估每一笔交易。对高风险交易可能触发 3DS 挑战。
`N`	跳过风险评估。所有交易走无摩擦流程。

设置为 N 时，卡片使用无摩擦 3DS 身份验证机制。交易无需输入 OTP 即可完成，并被视为持卡人已验证。因此，此类交易无法以欺诈或未授权使用为由发起争议。为增强安全性，建议保持该字段为 Y。

创建卡片时设置

{
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_currency": "USD",
  "card_limit": 2100.02,
  "risk_controls": {
    "allow_3ds_transactions": "N"
  }
}

对已有卡片更新

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_controls": {
      "allow_3ds_transactions": "N"
    }
  }'

创建卡片时如果省略 allow_3ds_transactions，默认值为 Y。
更新卡片时如果省略该字段，当前设置保持不变。
实体卡激活后，allow_3ds_transactions 自动设置为 Y。
该设置仅影响 3DS 行为，不影响其他风控检查。

OTP 下发

触发 3DS 挑战时，OTP 会发送到持卡人注册的邮箱。持卡人在身份验证页面输入 OTP 完成验证。

创建或更新持卡人时务必填写准确的邮箱。OTP 有效期为几分钟。

3DS OTP webhook

生成 OTP 时，UQPAY 会发送 card.3ds.otp webhook：

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.3ds.otp",
  "event_id": "26de83a5-cea5-4f84-ab11-48813025e40a",
  "source_id": "12ea604d-5899-43d6-8c2d-618c9ce8eae3",
  "data": {
    "otp": "12344444",
    "reference_code": "4868798",
    "customer_id": "67f006f4-d593-49f4-be0e-f1f894e8933b",
    "card_id": "1d749d10-511e-469f-9a83-0560a602ac37",
    "card_number": "1234********3381",
    "transaction_currency": "USD",
    "transaction_amount": "100",
    "merchant_name": "Example Merchant"
  }
}

入门

持卡人

卡片

充值

管理与安全

集成

参考

两字段交互逻辑

配置 `enable_3ds`

创建卡片时设置

对已有卡片更新

配置 `allow_3ds_transactions`

创建卡片时设置

对已有卡片更新

OTP 下发

3DS OTP webhook

​两字段交互逻辑

​配置 enable_3ds

​创建卡片时设置

​对已有卡片更新

​配置 allow_3ds_transactions

​创建卡片时设置

​对已有卡片更新

​OTP 下发

​3DS OTP webhook

​相关文档

两字段交互逻辑

配置 `enable_3ds`

创建卡片时设置

对已有卡片更新

配置 `allow_3ds_transactions`

创建卡片时设置

对已有卡片更新

OTP 下发

3DS OTP webhook

相关文档