PayPal JavaScript SDK v6 迁移 2026：Safari 结账验收

PayPal 官方迁移指南指出，v5 常见写法是通过带 client-id 的 SDK 脚本加载 PayPal；v6 使用新的核心脚本，并通过 createInstance 初始化，再创建支付会话。v6 还要求显式检查支付方式资格，并把订单创建、批准、捕获等逻辑放进支付会话。(developer.paypal.com)

因此，第一步不是打开结账页看按钮，而是盘点所有入口：

• 商品详情页上的快捷支付按钮。
• 购物车页上的 PayPal Checkout 入口。
• 独立结账页中的按钮、卡支付或其他钱包组件。
• 移动端落地页、促销页、订阅页或自定义支付弹窗。
• 返回商店、取消付款、支付失败后的重新尝试入口。

对每个入口记录 4 项内容：

1. 当前实际加载的 SDK 地址。
2. 初始化方法与组件名称。
3. 订单创建、批准、捕获分别由哪一端负责。
4. 失败时回退到 v5、其他支付方式，还是直接阻止上线。

PayPal 当前浏览器支持文档列出桌面 Safari 8 及以上、移动 Safari 9 及以上，但“支持”不代表每一种支付方式、弹窗策略、地区和账户状态都会呈现相同结果。资格判断仍会受到买家位置、币种、设备和账户状态影响。(developer.paypal.com)

如果 PayPal v6 按钮在 Safari 不显示，先不要立即修改 Safari 隐私设置。我们建议按下面的顺序定位：

1. 在 Safari 打开目标页面，选择“Safari > 设置 > 高级”，启用“显示网页开发者功能”。Apple 说明，Safari 的开发菜单、Web Inspector 和 WebDriver 默认可能未开启。(developer.apple.com)
2. 打开“开发 > 显示网页检查器”，进入 Sources、Console 和 Network 面板，分别查看脚本资源、控制台错误和网络请求。
3. 检查是否实际加载了 https://www.paypal.com/web-sdk/v6/core；沙盒应使用对应的 sandbox.paypal.com 核心脚本地址。不要只看页面源代码，要看 Network 中的实际请求。(developer.paypal.com)
4. 确认初始化代码在 SDK 的 onload 之后执行。PayPal 明确提示，如果 window.paypal.createInstance 尚未存在，通常是核心脚本尚未完成加载。
5. 查看 findEligibleMethods 或等效资格检查返回的实际结果。v6 按钮默认可以处于隐藏状态，只有在初始化完成并确认支付方式可用后，页面才应移除隐藏属性。
6. 检查 Content Security Policy、脚本 nonce、扩展程序和重复初始化。Safari 控制台中的 CSP 拒绝、跨源请求失败、未捕获 Promise 错误，都应截图并记录时间。
7. 使用同一商品、币种、语言和测试账户，在另一款受支持浏览器中复测。其他浏览器成功只能帮助判断问题是否偏向 Safari，不能替代 Safari 验收。

最小化记录可以采用这样的格式：

页面入口：
SDK 实际地址：
初始化结果：
资格检查结果：
Safari 版本：
控制台错误：
网络请求状态：
截图文件名：
责任人：

这里的关键不是“按钮有没有出现”，而是能否证明按钮由 v6 正确初始化、资格检查结果合理，并且点击后进入可追踪的支付会话。

PayPal Checkout 的登录环节至少要覆盖 4 种结果：弹窗正常打开、弹窗被阻止、买家主动关闭、登录中断后返回商店。

Safari 支持按网站配置弹窗策略。Apple 给出的路径是“Safari > 设置 > 网站 > 弹出式窗口”，可以对当前网站选择“允许”“阻止并通知”或“阻止”。(support.apple.com)

测试时不要直接把所有弹窗都改成允许。更可靠的做法是：

• 使用同一个沙盒买家账户。
• 固定商品、金额、币种、语言和入口页面。
• 每次只改变一个变量。
• 清理该站点的网站数据后重新开始。
• 记录弹窗是否打开、是否回到原标签页、页面是否出现重复提交。
• 复测“买家关闭弹窗”后，页面是否保留购物车内容，并提供再次付款入口。

Safari 的“防止跨网站跟踪”会定期删除第三方内容提供商的跟踪数据；Apple 也说明，部分网站依赖第三方内容提供商。支付弹窗涉及跨站跳转、网站数据和会话状态，因此应把网站数据、跨站跟踪和扩展程序作为测试变量记录，而不是要求买家永久关闭隐私保护。(support.apple.com)

如果只有在关闭隐私保护、禁用扩展程序或永久允许弹窗后才能完成付款，应将结果标为“需要技术复核”。可接受的修复方向通常是：

• 让支付流程在用户点击事件中启动，避免被浏览器视为非用户触发。
• 使用 PayPal 支持的自动展示模式与可恢复错误处理。
• 在弹窗失败后提供明确的重试或替代支付入口。
• 检查回调页面是否被缓存、重定向或重复提交。
• 让服务端根据订单状态决定是否继续，而不是依赖前端页面提示。

PayPal v6 的高级配置文档提供了展示模式回退思路，例如在可恢复错误出现时依次尝试不同展示方式；这比单纯要求买家修改浏览器隐私设置更适合作为产品修复方向。(developer.paypal.com)

沙盒中不要只执行一次“登录—批准—成功”。至少执行以下 3 条主路径：

批准付款

1. 从固定入口进入结账。
2. 点击 PayPal 按钮。
3. 使用沙盒买家账户登录。
4. 批准付款。
5. 返回商店后记录页面提示、购物车状态和订单号。
6. 在后台查询订单创建、批准与捕获状态。
7. 核对独立站订单是否进入正确的待履约或已付款状态。

主动取消

1. 打开 PayPal 登录或确认界面。
2. 主动关闭窗口，或选择返回商店。
3. 确认独立站没有生成已付款订单。
4. 确认购物车仍然存在。
5. 检查页面是否出现重新付款入口。
6. 再次点击支付，确认不会复用错误的旧状态。

失败或中断

1. 模拟登录中断、弹窗阻止或支付方式不可用。
2. 检查 onError、页面错误提示和服务端日志。
3. 确认按钮不会无限转圈。
4. 确认重复点击不会创建多个业务订单。
5. 记录是否可以切换到其他支付方式。

PayPal 官方上线清单要求测试批准、取消和错误回调，同时验证弹窗阻止处理、资格逻辑、订单捕获、履约流程、Webhook 和监控。(developer.paypal.com)

PayPal 沙盒支付成功后没有独立站订单，常见原因不是“Safari 没有跳转”，而是订单链路没有闭合：

• 前端创建了 PayPal 订单，但没有把返回的 orderId 正确交给服务端。
• 买家批准了订单，但服务端没有执行捕获。
• 捕获接口失败，前端却先展示了成功页面。
• 独立站使用异步队列，订单写入失败但没有告警。
• 取消、重复点击或刷新页面造成业务订单状态错乱。
• 沙盒买家账户、商家账户或环境端点配置不一致。

PayPal v6 文档明确要求，createOrder() 返回能够解析为 { orderId: "..." } 的结果。服务端应根据订单标识查询和捕获，而不是把浏览器回跳参数直接当成已收款凭证。(developer.paypal.com)

PayPal 的错误文档还建议根据订单 ID 查询订单，以获取捕获 ID 或 PayPal 交易 ID；如果订单未批准，则应要求买家重新完成批准流程。(developer.paypal.com)

验收记录至少要关联：

• 独立站业务订单号。
• PayPal orderId。
• 捕获 ID 或交易 ID。
• 创建、批准、捕获接口响应。
• 前端回调名称。
• 沙盒活动记录。
• 最终履约状态。

上线判断应依据服务端确认的捕获状态。浏览器显示“付款成功”、买家返回成功页，或者前端收到 onApprove，都不能单独触发发货、开通服务或标记订单已支付。

美国买家结账测试的目标，是验证目标市场入口在真实 Safari 中是否能完成完整链路，而不是证明某个美国 IP 能解决所有问题。远程 Mac 可以用于准备稳定的 macOS、Safari 和隔离网站数据环境，也可以让异地团队共享同一套复测脚本；但它不能绕过 PayPal 的账户政策、支付资格或风控判断。

如果团队没有本地 Mac，可先参考 MESHLAUNCH 的远程 Mac 方案，再根据测试团队所在地查看 美国东部节点的 Mac 租赁选项。选择节点时关注的是测试变量是否可重复，而不是把节点宣传成交易成功保证。

美国买家复测建议固定以下变量：

• 美国落地页入口。
• 商品、库存、运费和税费显示。
• 美元币种。
• 买家语言。
• Safari 网站数据状态。
• 弹窗策略。
• 测试账户。
• 订单创建、捕获和履约接口版本。

完成后按下面的清单做交付：

• [ ] 商品页、购物车页和结账页都已盘点。
• [ ] 已确认每个入口实际加载的是 v6 核心脚本。
• [ ] 已记录初始化、资格检查和按钮显示证据。
• [ ] 已完成 Safari 弹窗允许、阻止并通知、买家关闭三种路径。
• [ ] 已完成批准付款、取消付款和错误回调测试。
• [ ] 已将 orderId、捕获结果和独立站订单逐一对应。
• [ ] 已验证重复点击、刷新和返回购物车不会重复下单。
• [ ] 已保留脱敏截图、时间、Safari 版本和控制台日志。
• [ ] 已在另一款浏览器中做对照，但没有用它替代 Safari 验收。
• [ ] 已准备原版本或其他支付方式的回退路径。
• [ ] 已由业务负责人、测试人员和技术负责人共同签字。

满足“关键路径通过、服务端状态可核对、失败时有可用回退、证据完整”时，可以考虑小范围发布。只要订单捕获、Safari 登录弹窗或取消后的状态存在不可解释结果，就应延期，而不是用其他浏览器通过来掩盖缺口。

如果当前方案是共享电脑、临时远程桌面或不固定的海外网络，常见问题是网站数据容易串用、Safari 版本和扩展状态无法固定、网络出口不易复现，出现支付异常后也很难把截图、日志和订单状态对应起来。对于只需要短期完成迁移回归的团队，租用 MESHLAUNCH 的远程 Mac 通常比临时拼装测试环境更容易复用；但如果需要长期高频重负载、物理刷卡设备或本地接口，直接自购 Mac 仍可能更合适。

先用短周期远程 Mac 跑完 PayPal Checkout 的 Safari 验收矩阵，再决定是否进入正式上线，是成本和风险都更可控的做法。