验证 3DS 挑战

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

公共端点

此端点在付款人完成发卡行 iframe 中的 3DS（3D Secure 验证）挑战后调用。SDK 或您的重定向处理程序调用此端点以完成认证并继续支付。

---

请求头

请求头	值	必填
Content-Type	application/json	是

路径参数

字段	类型	必填	说明
uuid	string (UUID)	是	发起 3DS 认证的收费 UUID

请求体

字段	类型	必填	说明
transaction_id	string	是	来自挑战响应的 3DS 交易 ID

---

响应字段

字段	类型	说明
charge_uuid	string	收费标识符
authentication_status	string	authenticated、failed、attempted
eci	string	电子商务指示符（例如 05、06、07）
cavv	string	持卡人认证验证值
status	string	认证后的收费状态（confirmed、error）
message	array/null	认证失败时的错误详情

---

HTTP 状态码

状态码	说明
200	验证已处理
400	transaction_id 无效或缺少必填字段
404	收费未找到或无待处理的认证
409	认证已验证
422	认证会话已过期
429	超出请求频率限制
500	服务器内部错误

---

代码示例

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/public/charge/authentication/a1b2c3d4-e5f6-7890-abcd-ef1234567890/validate" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "d4e5f6a7-b8c9-0123-defg-h45678901234"}'

Python

import requests

charge_uuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

try:
    response = requests.post(
        f"https://core-manager.a55.tech/api/v1/bank/public/charge/authentication/{charge_uuid}/validate",
        json={"transaction_id": "d4e5f6a7-b8c9-0123-defg-h45678901234"},
        headers={"Content-Type": "application/json"},
    )
    response.raise_for_status()
    result = response.json()
    print(f"认证状态：{result['authentication_status']}——ECI：{result['eci']}")
    print(f"收费状态：{result['status']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"请求失败：{e}")

Node.js

const chargeUuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

try {
  const response = await fetch(
    `https://core-manager.a55.tech/api/v1/bank/public/charge/authentication/${chargeUuid}/validate`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        transaction_id: "d4e5f6a7-b8c9-0123-defg-h45678901234",
      }),
    }
  );

  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const result = await response.json();
  console.log(`认证状态：${result.authentication_status}——ECI：${result.eci}`);
  console.log(`收费状态：${result.status}`);
} catch (error) {
  console.error("3DS 验证失败：", error.message);
}

---

错误响应示例

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "authentication_status": "failed",
  "status": "error",
  "message": [
    {
      "code": "AUTHENTICATION_FAILED",
      "source": "3ds",
      "description": "Issuer rejected the 3DS challenge. Payer may retry or use a different card."
    }
  ]
}

---

配置 3DS →从头开始 3DS 流程。支付收费 →使用已认证的会话提交支付。查询收费 →认证后检查收费的最终状态。