> ## 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.
# 3D Secure
> Configure 3DS authentication behavior for online card transactions.
UQPAY supports 3D Secure (3DS) authentication to help prevent fraud on online transactions. Two card-level fields under `risk_controls` control 3DS behavior independently:
* **`enable_3ds`** — Whether the card is registered for 3DS at all.
* **`allow_3ds_transactions`** — Once registered, whether the cardholder must complete a challenge (e.g., OTP) or proceed via a frictionless flow.
3DS configuration support varies by card product. See [Card products](/card-issuance/v1.6/guide/card-products).
## How the two fields interact
| `enable_3ds` | `allow_3ds_transactions` | Behavior |
| ------------ | ------------------------ | ----------------------------------------------------------------------------------- |
| `N` | (any) | 3DS is skipped entirely. Online transactions proceed without 3DS authentication. |
| `Y` | `Y` | The cardholder may be challenged (OTP). |
| `Y` | `N` | Frictionless flow — no OTP, the transaction is treated as cardholder-authenticated. |
`allow_3ds_transactions` only takes effect when `enable_3ds` is `Y`. When `enable_3ds` is `N`, the card bypasses 3DS regardless of `allow_3ds_transactions`.
Controls whether the card is registered for 3DS.
Supported on **Business Visa** and **Personal Visa** only. Modifiable when the card is in `PENDING` or `ACTIVE` status.
Set at card creation
```json theme={null}
{
"cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
"card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
"card_currency": "USD",
"card_limit": 2100.02,
"risk_controls": {
"enable_3ds": "N"
}
}
```
Update on an existing card
```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
-H "x-auth-token: YOUR_API_TOKEN" \
-H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
-H "Content-Type: application/json" \
-d '{
"risk_controls": {
"enable_3ds": "N"
}
}'
```
* `enable_3ds` is returned in card responses only when it has been explicitly set on the card. When absent, the card follows the account-level 3DS configuration.
* `enable_3ds` is supported on Business Visa and Personal Visa only; it is ignored on Business Mastercard.
* To register 3DS but skip the challenge flow, set `enable_3ds` to `Y` and `allow_3ds_transactions` to `N`.
When `enable_3ds` is `N`, the card bypasses 3DS authentication entirely. Disputes based on fraud or unauthorized use cannot be raised for these transactions.
Once 3DS is registered, `allow_3ds_transactions` controls whether the challenge flow is allowed.
Supported on **Business Visa** only.
| Value | Behavior |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `Y` (default) | Risk engine evaluates each transaction. May trigger a 3DS challenge for high-risk transactions. |
| `N` | Bypasses risk evaluation. All transactions proceed via the frictionless flow. |
When set to `N`, the card uses a frictionless 3DS authentication mechanism. Transactions complete without OTP input and are treated as cardholder-authenticated. As a result, **disputes based on fraud or unauthorized use cannot be raised** for such transactions. For enhanced security, it is recommended to keep this set to `Y`.
Set at card creation
```json theme={null}
{
"cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
"card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
"card_currency": "USD",
"card_limit": 2100.02,
"risk_controls": {
"allow_3ds_transactions": "N"
}
}
```
Update on an existing card
```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
-H "x-auth-token: YOUR_API_TOKEN" \
-H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
-H "Content-Type: application/json" \
-d '{
"risk_controls": {
"allow_3ds_transactions": "N"
}
}'
```
* If `allow_3ds_transactions` is omitted during card creation, it defaults to `Y`.
* During card update, omitting the field leaves the current setting unchanged.
* Physical cards automatically have `allow_3ds_transactions` set to `Y` upon activation.
* This setting affects only 3DS behavior. Other fraud checks are not affected.
## OTP delivery
When a 3DS challenge is triggered, an OTP is sent to the cardholder's registered email address. The cardholder enters the OTP on the authentication page to complete verification.
Ensure the cardholder's email is accurate when creating or updating the cardholder. OTPs are valid for a few minutes.
## 3DS OTP webhook
UQPAY sends a `card.3ds.otp` webhook when an OTP is generated:
```json theme={null}
{
"version": "V1.6.0",
"event_name": "ISSUING",
"event_type": "card.3ds.otp",
"event_id": "26de83a5-cea5-4f84-ab11-48813025e40a",
"source_id": "12ea604d-5899-43d6-8c2d-618c9ce8eae3",
"data": {
"otp": "12344444",
"reference_code": "4868798",
"customer_id": "67f006f4-d593-49f4-be0e-f1f894e8933b",
"card_id": "1d749d10-511e-469f-9a83-0560a602ac37",
"card_number": "1234********3381",
"transaction_currency": "USD",
"transaction_amount": "100",
"merchant_name": "Example Merchant"
}
}
```
## Related
* [Create Card API](/card-issuance/v1.6/api-reference/create-card)
* [Update Card API](/card-issuance/v1.6/api-reference/update-card)
* [3DS OTP webhook](/card-issuance/v1.6/webhooks/3ds-otp)
* [Card products](/card-issuance/v1.6/guide/card-products)