> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D Secure

> 为线上卡交易配置 3DS 身份验证行为。

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

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

<Note>
  不同卡产品对 3DS 配置的支持有所不同。参见[卡产品](/zh/card-issuance/v1.6/guide/card-products)。
</Note>

<h2 id="how-the-two-fields-interact">两字段交互逻辑</h2>

| `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。

<h2 id="configure-enable-3ds">配置 `enable_3ds`</h2>

控制卡片是否注册 3DS。

仅 **Business Visa** 和 **Personal Visa** 支持。卡片处于 `PENDING` 或 `ACTIVE` 状态时可修改。

<h3 id="set-enable-3ds-at-card-creation">创建卡片时设置</h3>

```json theme={null}
{
  "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"
  }
}
```

<h3 id="update-enable-3ds-on-an-existing-card">对已有卡片更新</h3>

```bash theme={null}
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"
    }
  }'
```

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

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

<h2 id="configure-allow-3ds-transactions">配置 `allow_3ds_transactions`</h2>

注册 3DS 之后，`allow_3ds_transactions` 控制是否允许走挑战流程。

仅 **Business Visa** 支持。

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

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

<h3 id="set-allow-3ds-at-card-creation">创建卡片时设置</h3>

```json theme={null}
{
  "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"
  }
}
```

<h3 id="update-allow-3ds-on-an-existing-card">对已有卡片更新</h3>

```bash theme={null}
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"
    }
  }'
```

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

<h2 id="otp-delivery">OTP 下发</h2>

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

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

<h2 id="3ds-otp-webhook">3DS OTP webhook</h2>

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

```json theme={null}
{
  "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"
  }
}
```

<h2 id="related">相关文档</h2>

* [Create Card API](/zh/card-issuance/v1.6/api-reference/create-card)
* [Update Card API](/zh/card-issuance/v1.6/api-reference/update-card)
* [3DS OTP webhook](/zh/card-issuance/v1.6/webhooks/3ds-otp)
* [卡产品](/zh/card-issuance/v1.6/guide/card-products)