对接Viva Wallet原生结账v2API:渲染ACS跳转HTML完成交易获取chargeToken
Viva Wallet原生结账v2 3DS认证流程正确实现指南
核心问题根因
之前触发PaymentsCardHolderAuthenticationInvalidStatus(状态码400,事件ID2061)的本质原因,是拿到包含redirectToACSForm的首次支付响应后,没有正确完成ACS内容渲染与3DS流程闭环,导致预生成的chargeToken始终处于「未完成持卡人认证」的无效状态,甚至被直接复用发起扣款,最终触发拒收。
正确实现步骤
1. 首次收到支付响应后的渲染处理
当提交卡号信息后接口返回同时包含chargeToken与redirectToACSForm时,这个阶段的chargeToken仅为预生成凭证,不具备有效交易资格,绝对不能直接用来发起扣款。
对ACS内容的正确渲染操作:
- 优先使用全屏悬浮iframe承接这段HTML内容,不要直接替换当前结账页的DOM(避免破坏原有页面操作上下文)
- 必须将
redirectToACSForm返回的原始HTML字符串,直接赋值给iframe的srcdoc属性,不要对内容做HTML转义、也不要手动拆解拼接表单——这段内容本身是发卡行ACS服务自动生成的、可自动触发跳转的验证表单 - 参考渲染逻辑(前端伪代码):
这段HTML加载完成后,会自动跳转到发卡行的3DS验证页面,不需要额外写提交逻辑。const acsContainer = document.createElement('iframe') acsContainer.style = 'position: fixed; inset: 0; width: 100%; height: 100%; border: 0; z-index: 9999;' // 直接透传后端返回的ACS字符串,不要做额外处理 acsContainer.srcdoc = res.redirectToACSForm document.body.appendChild(acsContainer)
2. 3DS回跳后的校验逻辑
持卡人在ACS页面完成验证(输入密码/验证码等)后,会自动跳转到你预先配置的支付回调地址,这一环节需要完成两个校验:
- 后端接口先根据回跳携带的认证参数,拉取本次支付的最新状态,确认3DS认证结果为「已通过」
- 确认认证通过后,再返回对应有效状态的chargeToken给前端,这时候的token才可以用来发起后续扣款操作
3. 中断场景的兜底处理
针对「用户在3DS认证中途关闭浏览器/页面」的高频中断场景,需要做两层兜底避免无效报错:
- 前端层:监听ACS iframe的页面卸载事件,一旦检测到用户中途退出,直接提示「3DS认证未完成,请重新发起支付」,不要把之前预生成的chargeToken存在本地缓存复用
- 后端层:收到扣款请求时,先校验对应chargeToken关联的认证状态,如果状态为「未完成/中断」,直接返回前端引导重新走支付流程,不要基于失效token做重试
避坑提示
- 不要把
redirectToACSForm当成普通跳转URL处理,它是完整的HTML表单片段,需要直接渲染 - 不要在首次拿到chargeToken时就发起扣款,必须等3DS认证流程闭环完成后再使用
- 不要对ACS返回的HTML做转义处理,否则会导致表单失效,用户根本看不到发卡行的验证页面
注意:只要3DS认证环节出现中断,对应的预生成chargeToken就会永久失效,不可二次复用
内容的提问来源于stack exchange,提问作者Cleber Castiglioni
相关产品推荐
相关产品推荐

