配置 3DS 认证

POST/api/v1/bank/public/setup-authentication

公共端点

此端点由 A55Pay SDK 从付款人的浏览器调用。无需 Bearer token。它在卡片支付前初始化 3DS DDC（设备数据采集）流程。

---

请求头

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

请求体

字段	类型	必填	说明
card_bin	string	是	卡号的前 6-8 位数字
wallet_uuid	string (UUID)	是	与收费关联的钱包
merchant_id	string (UUID)	是	商户标识符

---

响应字段

字段	类型	说明
session_id	string	DDC 会话标识符——传递给 device_info.session_id
ddc_url	string	发卡行 DDC iframe 的 URL
ddc_jwt	string	DDC iframe 的 JWT token
provider	string	处理认证的 3DS 提供商
expires_at	string	ISO 8601 格式的会话过期时间

---

HTTP 状态码

状态码	说明
200	3DS 配置已初始化
400	BIN 无效或缺少必填字段
404	钱包或商户未找到
422	卡片 BIN 不符合 3DS 条件
429	超出请求频率限制
500	服务器内部错误

---

代码示例

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/public/setup-authentication \
  -H "Content-Type: application/json" \
  -d '{
    "card_bin": "402400",
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111"
  }'

Python

import requests

try:
    response = requests.post(
        "https://core-manager.a55.tech/api/v1/bank/public/setup-authentication",
        json={
            "card_bin": "402400",
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
        },
        headers={"Content-Type": "application/json"},
    )
    response.raise_for_status()
    setup = response.json()
    print(f"会话 ID：{setup['session_id']}")
    print(f"DDC URL：{setup['ddc_url']}")
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

try {
  const response = await fetch(
    "https://core-manager.a55.tech/api/v1/bank/public/setup-authentication",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        card_bin: "402400",
        wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        merchant_id: "11111111-1111-1111-1111-111111111111",
      }),
    }
  );

  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const setup = await response.json();
  console.log(`会话 ID：${setup.session_id}`);
  console.log(`DDC URL：${setup.ddc_url}`);
} catch (error) {
  console.error("3DS 设置失败：", error.message);
}

---

错误响应示例

{
  "status": "error",
  "message": [
    {
      "code": "BIN_NOT_3DS_ELIGIBLE",
      "source": "authentication",
      "description": "Card BIN 999999 is not eligible for 3DS authentication"
    }
  ]
}

---

支付收费 →在 DDC 完成后提交带有 device_info 的支付。验证 3DS →处理 3DS 挑战验证回调。创建收费 →使用 threeds_authentication: true 创建收费。