Payments

简体中文

English

简体中文

English

主题

Apple Pay 故障排除 ​

本文档介绍 Apple Pay 与 Onerway 集成的常见错误场景和解决方案。

前提条件

  • 向 Onerway 申请了 Apple Pay 支付
  • Onerway 已配置 Apple Pay 支付
  • 已完成基础配置（参见 账号配置）
  • 已了解支付流程（参见 支付流程）

现象 ​

问题描述

  1. 页面不显示 Apple Pay 按钮
  2. 页面显示 Apple Pay 按钮，点击后支付表单短暂显示后立即消失
  3. 确认支付后，页面显示支付未完成

常见错误场景 ​

测试卡问题 ​

测试卡问题

问题原因：

  • 测试卡问题
  • 测试卡过期
  • 测试卡被拒

解决方案：

  1. 检查测试环境：

    • 确认使用的是 Tester Apple ID，请参考 创建沙盒 Apple 账户
    • 验证测试账号的国家地区
      • 查看 设置-通用-语言与地区 是否为 澳大利亚、加拿大、法国、香港、爱尔兰、意大利、日本、新西兰、俄罗斯、新加坡、西班牙、台湾、英国、美国
      • 如果不是，请切换到非大陆国家，如美国、英国等

  2. 使用正确的测试卡：

    • 使用 Apple Pay 官方提供的测试卡，详见 测试卡列表
    • 确保测试卡未过期且信息输入正确
    • 验证测试卡已添加到 Apple Wallet 中

设备支持问题 ​

设备不支持 Apple Pay

问题原因：

  • 非 Safari 浏览器（Chrome、Firefox 等）
  • 非 HTTPS 环境
  • 设备不支持 Apple Pay（非苹果设备、旧版本 iOS - 版本低于 11.2）
  • 用户未添加支付卡片到 Apple Wallet
  • 所在国家或地区不支持 Apple Pay

解决方案：

  1. 用户指导：

    • 提示用户使用 Safari 浏览器
    • 引导用户在 Apple Wallet 中添加支付卡片
    • 提供设备兼容性说明页面

  2. 产品策略：

    • 将其他支付方式设为主要选项
    • 在支持 Apple Pay 的设备上才显示 Apple Pay 选项（参见 会话初始化：ApplePaySession.canMakePayments()）
    • 提供清晰的支付方式选择界面

  3. 用户体验：

    • 不显示不可用的支付选项
    • 提供友好的错误提示
    • 确保备选支付流程顺畅

  4. 国家/地区支持：

商户验证失败 ​

商户验证失败

问题原因：

  • 商户身份证书配置错误 - 仅针对商户自有账号模式
  • 域名验证文件缺失或不可访问
  • 商户标识符配置问题
  • 验证接口传递的 domainName 与配置的 domainName 不一致 - 仅针对商户自有账号模式
  • 后端验证接口异常

解决方案：

  1. 证书和配置问题：

    • 联系 Onerway：证书过期或配置错误需要 Onerway 重新生成
    • 检查域名验证文件：确保 /.well-known/apple-developer-merchantid-domain-association 文件存在且可访问（参见 账号配置：域名验证）
    • 检查 domainName：确保验证接口传递的 initiativeContext 与配置的 domainName 一致（仅针对商户自有账号模式）
    • 验证 HTTPS：确保网站使用有效的 SSL 证书

  2. 环境配置：

    • 生产环境：使用正确的生产环境商户标识符
    • 测试环境：使用沙箱环境配置
    • 域名白名单：确保当前域名已在 Apple Pay 配置中注册

  3. 运维和监控：

    • 设置证书过期提醒
    • 定期检查域名验证文件可访问性
    • 监控验证失败率

  4. 应急处理：

    • 提供明确的错误提示
    • 及时切换到备选支付方式
    • 联系 Onerway 技术支持获取帮助

支付处理错误 ​

支付授权或处理失败

问题原因：

  • 支付处理证书状态异常
  • 支付处理异常
  • Onerway 配置异常

解决方案：

  1. 联系 Onerway：
    • 联系 Onerway 技术支持获取帮助

技术自检清单 ​

环境配置自检 ​

在联系技术支持之前，请先执行以下自检步骤：

基础环境检查 ​

  • HTTPS 验证：确认网站使用 HTTPS 协议
  • SSL 评级：在 SSL Labs 确认达到 A 级
  • 域名验证文件：确认 /.well-known/apple-developer-merchantid-domain-association 可访问
  • 浏览器兼容性：确认在 Safari 浏览器中测试

代码实现检查 ​

  • 设备支持检测：ApplePaySession.canMakePayments() 返回 true
  • 会话创建：new ApplePaySession(3, paymentRequest) 成功创建
  • 事件绑定：onvalidatemerchant 和 onpaymentauthorized 事件已正确绑定
  • 错误处理：oncancel 和异常处理已实现

配置验证检查 ​

  • Merchant ID：确认使用正确的商户标识符（参见 账号配置）
  • 支付方式配置：从 支付方式查询接口 获取的配置正确
  • 域名一致性：前端域名与后端验证域名一致
  • 证书状态：确认证书未过期且配置正确

调试工具和方法 ​

浏览器调试 ​

javascript
// 检查 Apple Pay API 可用性
console.log('Apple Pay API available:', !!window.ApplePaySession); 
console.log('Can make payments:', ApplePaySession.canMakePayments()); 

// 检查支付方式支持
ApplePaySession.canMakePaymentsWithActiveCard('your-merchant-id')
  .then(canMakePayments => {
    console.log('Can make payments with active card:', canMakePayments); 
  });

网络请求检查 ​

  • 商户验证请求：检查 onvalidatemerchant 事件触发的网络请求
  • 支付处理请求：检查 onpaymentauthorized 事件触发的 Onerway API 调用
  • 响应状态：确认所有 API 请求返回正确的状态码
  • 错误日志：检查浏览器控制台和网络面板的错误信息

常见调试命令 ​

bash
# 检查域名验证文件
curl -I https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

# 检查 SSL 配置
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

# 验证 DNS 解析
nslookup yourdomain.com

获取技术支持 ​

联系 Onerway 支持时请准备 ​

  1. 基础信息：

    • 商户号和集成模式（自有账号/代理模式）
    • 问题发生的具体时间和环境（测试/生产）
    • 用户设备信息（iOS 版本、Safari 版本）

  2. 技术细节：

    • 完整的错误日志和控制台输出
    • 网络请求的详细信息（请求/响应内容）
    • 已完成的自检清单结果

  3. 重现步骤：

    • 问题的详细重现步骤
    • 预期行为与实际行为的对比
    • 问题发生的频率和影响范围

相关文档链接 ​