> ## 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 Integration Guide - Option 1
> Integrate 3D Secure authentication using option 1 to add an extra layer of security to online card transactions.
## 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:
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
```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"
}
```
### Sample Response (REQUIRES\_CUSTOMER\_ACTION)
```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": ""
}
},
"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.