Sagepay(Opayo) Direct 4.0升级后生产环境3D Secure页面异常求助

问题背景 #

将Opayo（原Sagepay）Direct从v2.23升级到v4.0后，生产环境3D Secure页面加载异常：

• 测试环境3D认证流程正常
• 生产环境仅Soldo虚拟卡可正常完成，Amex卡显示内部错误，Mastercard卡iframe无内容卡住

核心排查点与修复建议 #

1. 3DS参数配置问题 #

（1）Apply3DSecure参数设置

当前设置为Apply3DSecure=0，v4.0版本中该参数取值逻辑已更新：

• 0表示强制跳过3DS，但Amex、Mastercard等卡组织在生产环境要求必须触发3DS验证，强制跳过会导致ACS返回错误
• 建议改为Apply3DSecure=1（根据卡组织规则自动判断是否触发3DS）或Apply3DSecure=2（强制触发3DS），符合SCA合规要求

（2）浏览器信息参数完整性

当前BrowserUserAgent仅设置为Mozilla，生产环境中ACS需要完整的UA字符串（如Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36），不完整的UA会导致ACS无法识别浏览器环境，引发加载异常。

（3）ThreeDSNotificationURL与TermUrl合规性

• 确保两个URL均为HTTPS协议，生产环境不支持HTTP
• 检查URL中的特殊字符是否正确编码（比如ThreeDSNotificationURL中直接拼接VendorTxCode，需确认无编码冲突）

2. ACS表单提交错误 #

当前表单存在两处致命问题：

<form name="form" action="{$ACSURL}?creq=".$strCReq" method="POST">
    <input type="hidden" name="PaReq" value="{$strPAReq}"/>
    <input type="hidden" name="creq" value="{$strCReq}"/>
    <input type="hidden" name="TermUrl" value="{$TermUrl}?VendorTxCode={$strVendorTxCode}"/>
    <input type="hidden" name="MD" value="{$strMD}"/>
    <input type="hidden" name="VPSTxId" value="{$strVPSTxId}"/>
    <input type="hidden" name="mode" value="secure3d"/> 
</form>

• 错误1：action属性中同时通过URL拼接和POST传递creq参数，导致参数重复，ACS无法正确解析
• 错误2：混合使用模板变量{$ACSURL}和PHP变量.$strCReq，生成的URL大概率无效
• 错误3：v4.0使用3DS2协议，PaReq是3DS1的参数，多余传递会导致ACS处理错误

修复后的表单代码：

<form name="form" action="{$ACSURL}" method="POST">
    <input type="hidden" name="creq" value="{$strCReq}"/>
    <input type="hidden" name="TermUrl" value="{$TermUrl}?VendorTxCode={$strVendorTxCode}"/>
    <input type="hidden" name="MD" value="{$strMD}"/>
    <input type="hidden" name="mode" value="secure3d"/> 
</form>

3. COF/MIT参数合理性 #

当前设置的COFUsage=FIRST&InitiatedType=CIT&MITType=UNSCHEDULED用于连续支付场景，如果当前是单次消费交易，建议移除这些参数，避免ACS误解交易类型引发错误。

4. 生产环境专属配置验证 #

• 确认生产环境Opayo商户账号已开通3DS2权限，部分商户升级后需手动开启
• 检查生产环境服务器出站IP是否在Opayo允许的IP白名单中，IP受限会导致ACS请求失败
• 查看Opayo后台交易日志，获取StatusDetail字段的详细错误代码，这是排查生产问题的核心依据

验证步骤 #

1. 先修正ACS表单参数错误，移除多余的PaReq和action中的creq参数
2. 将Apply3DSecure改为1，补充完整的BrowserUserAgent字符串
3. 移除不必要的COF/MIT参数（如果是单次交易）
4. 测试Amex和Mastercard交易，验证流程是否恢复正常
5. 若仍有问题，提取Opayo后台的具体错误信息进一步排查

内容的提问来源于stack exchange，提问作者saikat guin