跳转到主要内容

3D Secure 验证

Quick Reference

What授权前的持卡人认证
Why责任转移至发卡行（issuer），通过 challenge 或无摩擦（frictionless）流程防范欺诈
Reading Time15 分钟
Difficulty中级
Prerequisites主机到主机或 SDK → 身份验证

3DS 在 A55 中的工作方式​

在收费上设置 threeds_authentication: true，并提供完整的 device_info 对象。A55 处理 3DS 协议、路由至发卡行并返回结果。

SDK 与 API

JavaScript SDK 通过 A55Pay.authentication() 自动运行设备数据采集（DDC，Device Data Collection）。服务端集成 H2H（主机到主机直连）在收费 JSON 中发送 device_info 字段。

无摩擦（frictionless）与 challenge​

方面无摩擦（Frictionless）Challenge
决策发卡行根据风险分静默批准发卡行要求持卡人交互
对体验的影响零（买家无感）跳转至 url_3ds 或 iframe 弹窗
何时发生低风险且设备数据丰富高风险或发卡行策略
转化最高较低（增加摩擦）
责任转移是是
典型占比3DS 交易的 70–85%15–30%

ECI 值​

分步集成​

1

从浏览器采集 device_info

在客户端采集真实浏览器值。每个字段都有助于发卡行的风险模型。

const deviceInfo = {
ip_address: await fetch('/api/ip').then(r => r.text()),
user_agent: navigator.userAgent,
http_accept_content: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
http_accept_browser_value: '*/*',
http_browser_language: navigator.language,
http_browser_java_enabled: navigator.javaEnabled?.() ?? false,
http_browser_javascript_enabled: true,
http_browser_color_depth: String(screen.colorDepth),
http_browser_screen_height: String(screen.height),
http_browser_screen_width: String(screen.width),
http_browser_time_difference: String(new Date().getTimezoneOffset()),
};
// 将 deviceInfo 发送至后端用于收费请求
2

创建收费并设置 threeds_authentication: true

curl -sS -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "type_charge": "credit_card",
  "card_name": "张伟",
  "card_number": "4111111111111111",
  "card_expiry_month": 12,
  "card_expiry_year": 2030,
  "card_cvv": "123",
  "amount": 10000,
  "currency": "BRL",
  "installment_count": 1,
  "threeds_authentication": true,
  "device_info": {
    "ip_address": "203.0.113.10",
    "user_agent": "Mozilla/5.0 ...",
    "http_accept_content": "text/html",
    "http_accept_browser_value": "*/*",
    "http_browser_language": "pt-BR",
    "http_browser_java_enabled": false,
    "http_browser_javascript_enabled": true,
    "http_browser_color_depth": "24",
    "http_browser_screen_height": "900",
    "http_browser_screen_width": "1440",
    "http_browser_time_difference": "180"
  },
  "webhook_url": "https://merchant.example/webhooks/a55",
  "redirect_url": "https://merchant.example/return"
}'
3

处理响应

响应始终返回完整的收费对象。根据结果变化的关键字段是 status、action_url 和 message。

{
  "charge_uuid": "a34f2499-2a40-40a5-8f5a-578002a88f51",
  "local_currency": 159.8,
  "currency": "EUR",
  "usd_currency": 185.59,
  "type": "credit_card",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-11",
  "status": "confirmed",
  "message": [],
  "installment_count": 1,
  "installments": [],
  "payment_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "",
  "session_id": null,
  "subscription": {},
  "reference_external_id": "10ccf81a-1de7-4a3e-b86d-f3f685e8ee57",
  "is_async": false
}

无需跳转——收费已静默完成认证。

4

处理 challenge 重定向（若为 `pending`）

若响应包含 action_url，请将买家重定向到该 URL。付款人完成 3DS 验证或指纹采集后，会自动重定向到您的 redirect_url。请始终以 webhook 作为最终交易状态的可靠来源。

if (response.action_url) {
  window.location.href = response.action_url;
}
challenge 流程如何运作
  1. 您的页面将付款人重定向到 action_url
  2. 付款人完成所需操作（3DS OTP、生物识别、指纹采集等）
  3. 完成后，付款人重定向到您的 redirect_url
  4. A55 向 webhook_url 发送包含最终交易状态（paid 或 error）的 webhook
5

通过 webhook 确认

请始终将 Webhook（网络钩子）作为事实来源（source of truth）。在收费上配置 webhook_url，以便在买家关闭浏览器时仍能收到异步更新。

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "paid",
  "transaction_reference": "txn_ref_001"
}

端到端流程​

device_info 字段​

字段类型必填说明
ip_addressstring是客户端公网 IP
user_agentstring是浏览器 user agent 字符串
http_accept_contentstring是HTTP Accept 头
http_accept_browser_valuestring是浏览器 Accept 值
http_browser_languagestring是浏览器语言（例如 pt-BR）
http_browser_java_enabledboolean是是否启用 Java 插件
http_browser_javascript_enabledboolean是是否启用 JavaScript
http_browser_color_depthstring是屏幕色深
http_browser_screen_heightstring是屏幕高度（像素）
http_browser_screen_widthstring是屏幕宽度（像素）
http_browser_time_differencestring是相对 UTC 的偏移（分钟）
device_idstring否稳定设备标识
session_idstring否结账会话 ID
数据质量

不完整或合成的 device_info 会提高 challenge 率与拒绝率。请在客户端采集真实浏览器值并传给服务器，切勿硬编码这些值。

SDK DDC（A55Pay.authentication）​

使用 JavaScript SDK 时，可单独运行 DDC：

A55Pay.authentication({
  transactionReference: 'charge-uuid-or-ref',
  cardBrand: 'visa',
  cardNumber: '4111111111111111',
  cardExpiryMonth: '12',
  cardExpiryYear: '2030',
  onSuccess: (payload) => {
    // payload 包含 sessionId、accessToken、referenceId
    // 将 sessionId 用于收费请求
  },
  onError: (err) => {
    // DDC 失败——继续（不使用会话）或处理错误
  },
});

说明： payV2() 会在处理前自动运行 DDC。仅当您手动管理流程时才需要调用 authentication()。

验证端点​

POST /api/v1/bank/public/charge/authentication/{uuid}/validate

请使用 3DS 流程中的收费 uuid。A55 会验证认证元数据并返回最终结果。

使用沙箱测试卡​

Card NumberBrandScenarioExpected Status
4111 1111 1111 1111Visa3DS 无摩擦——通过confirmed
4000 0000 0000 0101Visa3DS 需要 challengeconfirmed
4000 0000 0000 0002Visa3DS——发卡行拒绝declined
5500 0000 0000 0004Mastercard3DS 无摩擦——通过confirmed
4000 0000 0000 0069Visa3DS——处理错误error

希望在无 challenge 的情况下提高通过率？​

Visa Data Only 通过 3DS 通道向发卡行共享增强的交易数据——无需任何 challenge 跳转。在 Square 试点中，商户在 9 个月内、约 600 万笔交易上最高获得 +646 个基点 的提升。

无摩擦。无购物车放弃。A55 现支持通过单一标志启用：data_only: true。

代价是：无责任转移（欺诈由商户承担）。在拉美高流量、低风险的场景下，这一取舍往往能带来数倍回报。

了解如何启用 Data Only →

DataOnly 纯数据扣款 →Visa/Mastercard 数据专用路径——最高通过率。Host-to-Host 直连 →完整收费 API，含卡字段与 3DS 处理。SDK V2 →浏览器端采集卡信息，内置 DDC 与 3DS。