3DS Integration Guide - Option 1 - UQPAY Developer Docs

Overview

3D Secure (3DS) is an authentication protocol designed to provide an additional layer of security for online credit and debit card transactions. It helps prevent unauthorized card usage by requiring cardholders to authenticate themselves with their card issuer before completing a transaction. When 3DS is enabled, the cardholder is redirected to their card issuer’s authentication page where they must provide additional verification, typically through OTP (One-Time Password) or biometric authentication.

Integration Steps

Step 1: Enable 3DS in Payment Request

To enable 3DS authentication, include the following parameters in your Payment Intent creation or confirmation request:

Field	Type	Required	Description
`three_ds_action`	string	Yes	Set to `enforce_3ds` to require 3DS authentication
`browser_info`	object	Yes	Browser and device information collected from the customer’s device. This data is critical for risk assessment; inaccurate or missing information may cause the 3DS service provider to reject the transaction.
`ip_address`	string	Yes	The customer’s IP address

Step 2: Handle 3DS Authentication

After creating or confirming the Payment Intent with 3DS enabled:

Check the Payment Intent status in the response
If the status is REQUIRES_CUSTOMER_ACTION, examine the next_action field
If next_action.redirect_iframe.iframe is present, embed the provided iframe URL in your payment page
The iframe will automatically display the 3DS authentication interface for the customer to complete OTP input or other verification methods

Step 3: Handle Post-Authentication

After the payment process is completed (whether successful or failed), the customer is redirected to the return_url specified in the initial request. The redirect URL includes the merchant_order_id and other parameters, as shown in the example below:

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

Use the merchant_order_id to query the payment status and display the corresponding result to the customer.

API Example

Sample Request

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

Sample Response (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"
}

Note: All examples in this guide are for demonstration purposes only and should not be used in production.

Getting Started

Accept Payments

Manage Payments

Testing

Reference

3DS Integration Guide - Option 1

Overview

Integration Steps

Step 1: Enable 3DS in Payment Request

Step 2: Handle 3DS Authentication

Step 3: Handle Post-Authentication

API Example

Sample Request

Sample Response (REQUIRES_CUSTOMER_ACTION)

​Overview

​Integration Steps

​Step 1: Enable 3DS in Payment Request

​Step 2: Handle 3DS Authentication

​Step 3: Handle Post-Authentication

​API Example

​Sample Request

​Sample Response (REQUIRES_CUSTOMER_ACTION)

Overview

Integration Steps

Step 1: Enable 3DS in Payment Request

Step 2: Handle 3DS Authentication

Step 3: Handle Post-Authentication

API Example

Sample Request

Sample Response (REQUIRES_CUSTOMER_ACTION)