> ## 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.

# 3DS 集成指南 - 方式 1

> 使用方式 1 集成 3D Secure 身份验证，为线上卡交易增加一层安全保护。

<h2 id="overview">概览</h2>

3D Secure（3DS）是一种身份验证协议，用于为线上信用卡和借记卡交易提供额外的安全保护。它要求持卡人在完成交易前先向发卡机构进行身份验证，从而防止未授权用卡。

启用 3DS 后，持卡人会被跳转至发卡机构的身份验证页面，通常通过 OTP（一次性密码）或生物特征完成额外验证。

<h2 id="integration-steps">集成步骤</h2>

<h3 id="step-1-enable-3ds-in-payment-request">步骤 1：在支付请求中启用 3DS</h3>

要启用 3DS 身份验证，在 Payment Intent 创建或确认请求中加入以下参数：

| 字段                | 类型     | 必填 | 说明                                                           |
| ----------------- | ------ | -- | ------------------------------------------------------------ |
| `three_ds_action` | string | 是  | 设置为 `enforce_3ds` 以强制 3DS 身份验证                               |
| `browser_info`    | object | 是  | 从客户设备采集的浏览器和设备信息。这些数据对风险评估至关重要；信息不准确或缺失可能导致 3DS 服务提供方拒绝该笔交易。 |
| `ip_address`      | string | 是  | 客户的 IP 地址                                                    |

<h3 id="step-2-handle-3ds-authentication">步骤 2：处理 3DS 身份验证</h3>

创建或确认启用 3DS 的 Payment Intent 后：

1. 检查响应中的 Payment Intent 状态
2. 如果状态为 `REQUIRES_CUSTOMER_ACTION`，查看 `next_action` 字段
3. 如果 `next_action.redirect_iframe.iframe` 存在，将返回的 iframe URL 嵌入你的支付页面
4. iframe 会自动展示 3DS 身份验证界面，供客户完成 OTP 输入或其他验证

<h3 id="step-3-handle-post-authentication">步骤 3：处理身份验证后流程</h3>

支付流程完成后（无论成功或失败），客户会被跳转至初始请求中指定的 `return_url`。跳转 URL 会带上 `merchant_order_id` 和其他参数，示例如下：

```
https://return-url/api/v1/callback?&token=fRwcZj+HrgnMl33ISlEimuaOnErksvHCoqMj6DsPF8PjKdDjFSAtPreQDgnG8fxe2I58pnABxb47tekR2CS0Al7NgnNAeI9wU%2Fe7Hvg4zYveO5TSj4WHoJ+HjAwIc5wDzmkqX92wgU2KTOPUKPTJ6nas2xTA+A==&return_url=https://return-url/api/v1/callback&p=pending&mid=f43ee1d9-a38a-4487-b78b-96500cbf3da8
```

使用 `merchant_order_id` 查询支付状态，并向客户展示对应结果。

<h2 id="api-example">API 示例</h2>

<h3 id="sample-request">示例请求</h3>

```json theme={null}
{
    "amount": "8.88",
    "currency": "SGD",
    "payment_method": {
        "type": "card",
        "card": {
            "card_name": "mastercard 8012",
            "card_number": "5521970079998012",
            "expiry_month": "10",
            "expiry_year": "2028",
            "cvc": "001",
            "network": "mastercard",
            "billing": {
                "first_name": "acquiring",
                "last_name": "sandbox",
                "email": "acquiring.sandbox@uqpay.com",
                "phone_number": "0524-91353515",
                "address": {
                    "country_code": "SG",
                    "state": "Singapore",
                    "city": "Singapore",
                    "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
                    "postcode": "924011"
                }
            },
            "auto_capture": true,
            "authorization_type": "authorization",
            "three_ds_action": "enforce_3ds"
        }
    },
    "ip_address": "103.142.140.54",
    "browser_info": {
        "accept_header": "*/*",
        "browser": {
            "java_enabled": true,
            "javascript_enabled": true,
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
        },
        "device_id": "00000000-000000000000000",
        "language": "en-US",
        "location": {
            "lat": "-37.81892",
            "lon": "144.95913"
        },
        "mobile": {
            "device_model": "Apple IPHONE 7",
            "os_type": "IOS",
            "os_version": "IOS 14.5"
        },
        "screen_color_depth": 24,
        "screen_height": 1080,
        "screen_width": 1920,
        "timezone": "-2"
    },
    "merchant_order_id": "{{$guid}}",
    "description": "acquiring sandbox 3ds testing",
    "metadata": {
        "request_id": "{{$guid}}"
    },
    "return_url": "https://return-url/api/v1/callback"
}
```

<h3 id="sample-response-requires_customer_action">示例响应（REQUIRES\_CUSTOMER\_ACTION）</h3>

```json theme={null}
{
    "amount": "8.88",
    "available_payment_method_types": null,
    "cancel_time": "",
    "cancellation_reason": "",
    "captured_amount": "0",
    "client_secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtYXN0ZXJfaWQiOiIwIiwiYWNjb3VudF9pZCI6ImIxYjg5Njg0LWMyYzQtNGQ1NC1iOGE4LTM1NzI3MjdmZDEyMCIsImludGVudF9pZCI6IlBJMTk5NjQxMjk5NjI0NjU3MzA1NiIsImV4cCI6MTc2NDgxODcyNCwiaWF0IjoxNzY0ODE2OTI0fQ.gsf8RayDheK8LK8EpBUXiKlIyGB0b6mMkxmxr-2kYRk",
    "complete_time": "",
    "create_time": "2025-12-04T10:55:24+08:00",
    "currency": "SGD",
    "description": "acquiring sandbox 3ds testing",
    "intent_status": "REQUIRES_CUSTOMER_ACTION",
    "latest_payment_attempt": {
        "amount": "8.88",
        "attempt_id": "PA1996412996364013568",
        "attempt_status": "AUTHENTICATION_REDIRECTED",
        "captured_amount": "8.88",
        "complete_time": "",
        "create_time": "2025-12-04T10:55:24+08:00",
        "currency": "SGD",
        "failure_code": "",
        "refunded_amount": "0",
        "update_time": "2025-12-04T10:55:24+08:00"
    },
    "merchant_order_id": "55fc86a6-1621-4303-85cc-90424acc1215",
    "metadata": {
        "request_id": "5fc0fe47-53f4-443b-8143-7e4a85186483"
    },
    "next_action": {
        "redirect_iframe": {
            "iframe": "<iframe name=\"threeDSRedirectIframe\" id=\"threeDSRedirectIframe\" style=\"display: none; width: 0; height: 0; border: 0; visibility: hidden;\"></iframe><form id=\"threeDSRedirectForm\" method=\"POST\" target=\"_top\" action=\"https://sit-3dss-cpxy.hitrustpay.com.tw/sg/threeds-integrator/auth/2.1.0/Zn0PzVbMHipMwlo-SAlpj7Ph1ZkWCyuHthnpuDNGIBA\" style=\"display:none\" ><input type=\"hidden\" name=\"threedsIntegratorOid\" id=\"threedsIntegratorOid\" value=\"850953\" /></form><script>(function(){var form = document.getElementById(\"threeDSRedirectForm\"); form.submit();})();</script>"
        }
    },
    "payment_intent_id": "PI1996412996246573056",
    "return_url": "https://return-url/api/v1/callback",
    "update_time": "2025-12-04T10:55:24+08:00"
}
```

注：本指南中的所有示例仅用于演示，不应直接用于生产环境。