概览
3D Secure（3DS）是一种身份验证协议，用于为线上信用卡和借记卡交易提供额外的安全保护。它要求持卡人在完成交易前先向发卡机构进行身份验证，从而防止未授权用卡。 启用 3DS 后，持卡人会被跳转至发卡机构的身份验证页面，通常通过 OTP（一次性密码）或生物特征完成额外验证。集成步骤
步骤 1：在支付请求中启用 3DS
要启用 3DS 身份验证，在 Payment Intent 创建或确认请求中加入以下参数：| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
three_ds_action | string | 是 | 设置为 enforce_3ds 以强制 3DS 身份验证 |
browser_info | object | 是 | 从客户设备采集的浏览器和设备信息。这些数据对风险评估至关重要；信息不准确或缺失可能导致 3DS 服务提供方拒绝该笔交易。 |
ip_address | string | 是 | 客户的 IP 地址 |
步骤 2：处理 3DS 身份验证
创建或确认启用 3DS 的 Payment Intent 后：- 检查响应中的 Payment Intent 状态
- 如果状态为
REQUIRES_CUSTOMER_ACTION，查看next_action字段 - 如果
next_action.redirect_iframe.iframe存在，将返回的 iframe URL 嵌入你的支付页面 - iframe 会自动展示 3DS 身份验证界面，供客户完成 OTP 输入或其他验证
步骤 3：处理身份验证后流程
支付流程完成后（无论成功或失败），客户会被跳转至初始请求中指定的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 查询支付状态，并向客户展示对应结果。
API 示例
示例请求
{
"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"
}
示例响应（REQUIRES_CUSTOMER_ACTION）
{
"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"
}