Skip to main content

​
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:
FieldTypeRequiredDescription
three_ds_actionstringYesSet to enforce_3ds to require 3DS authentication
browser_infoobjectYesBrowser 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_addressstringYesThe customer’s IP address

​
Step 2: Handle 3DS Authentication

After creating or confirming the Payment Intent with 3DS enabled:
  1. Check the Payment Intent status in the response
  2. If the status is REQUIRES_CUSTOMER_ACTION, examine the next_action field
  3. If next_action.redirect_iframe.iframe is present, embed the provided iframe URL in your payment page
  4. 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.