> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/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 配置的支持有所不同。参见[卡产品](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md)。

## 两字段交互逻辑

| `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` 状态时可修改。

### 创建卡片时设置

```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"
  }
}
```

### 对已有卡片更新

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

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

## 配置 `allow_3ds_transactions`

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

仅 **Business Visa** 支持。

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

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

### 创建卡片时设置

```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"
  }
}
```

### 对已有卡片更新

```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 行为，不影响其他风控检查。

## OTP 下发

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

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

## 3DS OTP webhook

生成 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"
  }
}
```

## 相关文档

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.