跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

​
概览

3D Secure（3DS）是一种身份验证协议，用于为线上信用卡和借记卡交易提供额外的安全保护。它要求持卡人在完成交易前先向发卡机构进行身份验证，从而防止未授权用卡。 启用 3DS 后，持卡人会被跳转至发卡机构的身份验证页面，通常通过 OTP（一次性密码）或生物特征完成额外验证。

​
集成步骤

​
步骤 1：在支付请求中启用 3DS

要启用 3DS 身份验证，在 Payment Intent 创建或确认请求中加入以下参数：
字段类型必填说明
three_ds_actionstring是设置为 enforce_3ds 以强制 3DS 身份验证
browser_infoobject是从客户设备采集的浏览器和设备信息。这些数据对风险评估至关重要；信息不准确或缺失可能导致 3DS 服务提供方拒绝该笔交易。
ip_addressstring是客户的 IP 地址

​
步骤 2：处理 3DS 身份验证

创建或确认启用 3DS 的 Payment Intent 后：
  1. 检查响应中的 Payment Intent 状态
  2. 如果状态为 REQUIRES_CUSTOMER_ACTION，查看 next_action 字段
  3. 如果 next_action.redirect_iframe.iframe 存在，将返回的 iframe URL 嵌入你的支付页面
  4. 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": "[email protected]",
                "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"
}
注：本指南中的所有示例仅用于演示，不应直接用于生产环境。