Skip to main content

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.

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 BIN. See Supported BINs for risk control configurations.

​
How the two fields interact

enable_3dsallow_3ds_transactionsBehavior
N(any)3DS is skipped entirely. Online transactions proceed without 3DS authentication.
YYThe cardholder may be challenged (OTP).
YNFrictionless 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.

​
Configure enable_3ds

Controls whether the card is registered for 3DS. Visa cards only. Modifiable when the card is in PENDING or ACTIVE status.

​
Set at card creation

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

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 ignored for non-Visa cards.
  • 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.

​
Configure allow_3ds_transactions

Once 3DS is registered, allow_3ds_transactions controls whether the challenge flow is allowed.
ValueBehavior
Y (default)Risk engine evaluates each transaction. May trigger a 3DS challenge for high-risk transactions.
NBypasses 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

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

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