3DS 与托管收银台接入

3DS 的产品边界

1. 认证成功不等于扣款成功：认证只证明是持卡人本人，发卡行仍可能拒绝扣款；以支付的 status 为准。
2. 平台不能保证每次都不弹认证：可能无需交互，也可能需要在银行页面挑战，由发卡行与上游决定。
3. 不能靠商户配置绕过上游或发卡行的认证要求。

什么时候需要认证

在测试环境用 3DS 测试卡模拟无需交互、挑战成功、挑战失败与认证成功但扣款被拒等结果。

处理 next_action.redirect_to_url

在 API 参考中查看：next_action。

• 整页跳转：把 next_action.url 从你的服务端返回给付款人浏览器并整页跳转；不要放进 iframe（认证承载页禁止被第三方页面嵌入）。App 内用系统浏览器或应用内浏览器标签页打开。
• 发卡行挑战始终在平台认证承载页内完成（承载页按上游要求以内嵌框架或整页跳转展示发卡行页面）：你的页面不需要、也不能集成上游 3DS SDK。
• 有效期：next_action.expires_at 最长 10 分钟（取平台上限与上游会话有效期的较短者）。
• 安全：认证地址带只绑定这一笔认证的短时凭据，不能用于其他订单。不要写入日志、分析工具或错误上报；不要放进你自己页面的 URL（查询参数或 hash），以免经 Referer 或分析脚本泄漏。
• 不要在你的页面上收集发卡行密码或短信验证码；挑战信息只在发卡行或上游提供的认证流程中填写。
• 需要交互的认证不能由服务端代替持卡人完成：发起支付时付款人必须在场。
• type 首期只有 redirect_to_url；遇到不认识的类型按“未完成”处理并查询，不要当成功。

认证结束之后

付款人完成认证后，浏览器回到你在创建或确认支付时提供的 return_url。

上面每种结果都可以用 3DS 测试卡在测试环境复现。

浏览器信息采集

browser_info 用于 3DS 风险评估，必须来自付款人的真实浏览器。字段是否必填由当前上游能力决定，缺失时在提交上游前返回 400 并在 error.field 中指出字段；建议始终提供。

在 API 参考中查看：browser_info。

// 在付款人浏览器中采集，随卡信息一起提交到你的服务端
export function collectBrowserInfo() {
  return {
    user_agent: navigator.userAgent,
    language: navigator.language,
    screen_width: window.screen.width,
    screen_height: window.screen.height,
    color_depth: window.screen.colorDepth,
    timezone_offset_minutes: new Date().getTimezoneOffset(), // UTC+8 为 -480
    javascript_enabled: true
  };
}

timezone_offset_minutes 使用 JavaScript getTimezoneOffset() 的符号语义，与“UTC+8”的写法相反：

夏令时期间同一地区的值会变化，所以必须在付款时实时采集，不能写死。示例中的 203.0.113.x 是文档保留地址，不可用于生产。

托管收银台流程概览

• 收银台使用平台的独立域名。卡信息在收银台内由隔离的采集组件接收（上游托管组件，或平台独立子域上的隔离 iframe，由平台按上游能力选择，对你的接入没有差别），你的页面和服务端都不接触卡数据；创建请求中也没有卡数据。
• 收银台显示商户展示名、订单摘要（description）、金额与币种；不会显示你的服务端密钥。

创建收银会话的两种方式

两种方式都必须带 Idempotency-Key。方式 B 的示例见快速开始，方式 A：

# 方式 A：为已创建的 Payment（例如 confirm=false）创建收银会话
curl https://api.payhub.example/v1/checkout/sessions \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>" \
  -H "Idempotency-Key: order-demo-008-session-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "<PAYMENT_ID>",
    "return_url": "https://merchant.example/payment/return",
    "cancel_url": "https://merchant.example/payment/cancel",
    "locale": "zh-CN"
  }'

错误：两组参数都传或都缺 → 400 invalid_request；币种未在当前环境开通 → 403 capability_disabled（先于金额检查返回）；金额或币种与已有订单不一致 → 422 order_amount_mismatch；回跳地址未登记 → 422 url_not_allowed；订单不可支付 → 409。完整字段与响应示例见 POST/v1/checkout/sessions。

复用与有效期

收银台语言

locale 使用 BCP 47：以 zh 开头显示中文、以 en 开头显示英文，其他取值或未传时使用商户默认语言。付款人也可以在收银台页脚切换语言。

回跳地址白名单

• return_url、cancel_url（以及直接 API 的 return_url）必须匹配预先登记的规则，否则返回 422 url_not_allowed：登记回跳地址（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）。
• 规则按环境分别登记，由协议 + 主机（精确主机，或 *.example.com 一级通配）+ 可选端口 + 可选路径前缀组成。
• 路径前缀按路径段匹配：/pay 匹配 /pay/return，不匹配 /payment。查询串与片段不参与匹配。
• 生产只允许 https；测试环境可额外登记 http://localhost 等本地地址。
• 平台回跳时原样使用你提供的地址，不追加任何参数。

返回商户不等于撤销扣款

付款人点击“返回商户”（cancel_url）不等于撤销已提交的扣款。你的 cancel_url 页面要先查询支付：仍在途时显示“正在确认”；确认不存在在途扣款、需要关闭订单时，调用 POST/v1/payments/{payment_id}/cancel 并以 status=canceled 为准。

履约以服务端状态为准

• 浏览器回到 return_url 只用于体验。
• 履约依据只能是：服务端查询到的 status=succeeded，或经过验签的 payment.succeeded 事件（验签方法见 Webhook 验签步骤）。
• URL 参数（包括你自己放的订单号）不能当作结果，只能当作“去查哪一笔”的线索。
• 认证与收银凭据只绑定一个对象：A 订单的凭据不能操作 B 订单；你的系统也不要在订单之间复用这些地址。

// return_url / cancel_url 页面：只展示，结果以服务端查询为准；URL 参数只作为查找订单的线索
app.get('/payment/return', async (req, res) => {
  const order = await findOrderForSession(req.session.userId); // 从你的会话或订单表找到订单
  const payment = await getPayment(order.paymentId); // 服务端查询最新状态
  switch (payment.status) {
    case 'succeeded':
      return res.render('paid', { order }); // 履约由 Webhook 或服务端查询触发，页面只展示
    case 'failed':
      return res.render('failed', { order, message: payment.failure?.message }); // 可重新进入收银台换卡
    case 'canceled':
    case 'expired':
      return res.render('closed', { order });
    default:
      return res.render('confirming', { order }); // processing / requires_action / 未知：显示"正在确认"
  }
});

常见问题