跳转到主要内容

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 支持 3D Secure（3DS）身份验证，帮助防范线上交易欺诈。risk_controls 下有两个独立字段控制 3DS 行为：
  • enable_3ds —— 卡片是否注册 3DS。
  • allow_3ds_transactions —— 注册 3DS 之后，持卡人是否需要完成挑战（如 OTP），还是走无摩擦流程。
不同 BIN 对 3DS 配置的支持有所不同。参见支持风控配置的 BIN 列表。

​
两字段交互逻辑

enable_3dsallow_3ds_transactions行为
N（任意）完全跳过 3DS。线上交易不进入 3DS 身份验证。
YY持卡人可能被挑战（OTP）。
YN走无摩擦流程 —— 不需要 OTP，交易被视为持卡人已验证。
allow_3ds_transactions 仅在 enable_3ds 为 Y 时生效。当 enable_3ds 为 N 时，无论 allow_3ds_transactions 取值如何，卡片都会跳过 3DS。

​
配置 enable_3ds

控制卡片是否注册 3DS。 仅 Visa 卡支持。 卡片处于 PENDING 或 ACTIVE 状态时可修改。

​
创建卡片时设置

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

​
对已有卡片更新

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 仅在卡片显式设置过该字段时返回。未设置时，卡片继承 Account 级 3DS 配置。
  • 非 Visa 卡会忽略 enable_3ds。
  • 如要注册 3DS 但跳过挑战流程，将 enable_3ds 设为 Y、allow_3ds_transactions 设为 N。
当 enable_3ds 为 N 时，卡片完全跳过 3DS 身份验证。此类交易无法以欺诈或未授权使用为由发起争议。

​
配置 allow_3ds_transactions

注册 3DS 之后，allow_3ds_transactions 控制是否允许走挑战流程。
取值行为
Y（默认）风控引擎评估每一笔交易。对高风险交易可能触发 3DS 挑战。
N跳过风险评估。所有交易走无摩擦流程。
设置为 N 时，卡片使用无摩擦 3DS 身份验证机制。交易无需输入 OTP 即可完成，并被视为持卡人已验证。因此，此类交易无法以欺诈或未授权使用为由发起争议。为增强安全性，建议保持该字段为 Y。

​
创建卡片时设置

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

​
对已有卡片更新

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"
    }
  }'
  • 创建卡片时如果省略 allow_3ds_transactions，默认值为 Y。
  • 更新卡片时如果省略该字段，当前设置保持不变。
  • 实体卡激活后，allow_3ds_transactions 自动设置为 Y。
  • 该设置仅影响 3DS 行为，不影响其他风控检查。

​
OTP 下发

触发 3DS 挑战时，OTP 会发送到持卡人注册的邮箱。持卡人在身份验证页面输入 OTP 完成验证。
创建或更新持卡人时务必填写准确的邮箱。OTP 有效期为几分钟。

​
3DS OTP webhook

生成 OTP 时，UQPAY 会发送 card.3ds.otp webhook： 
{
  "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"
  }
}