sumup-debug

SumUp 故障排查手册

使用此技能诊断和修复故障的 SumUp 集成。

快速分诊矩阵

1. 对症状进行分类：
   • 身份验证/签名错误
   • 创建/处理结账时出错
   • 组件/客户端挂载或流程错误
   • 异步状态不一致（UI 显示成功，后端状态却显示失败）
2. 收集证据：
   • 请求/响应负载（已脱敏）、HTTP 状态、错误代码/消息
   • 结账 ID、商户代码、checkout_reference
   • Webhook 投递 ID 和签名验证结果
3. 在更改生产环境行为之前，先在沙盒中复现问题。

常见故障及修复方法

HMAC 签名不匹配（x-payload-signature）

症状：

• 所有事件或部分事件的 Webhook 验证失败。

可能原因：

• 请求体解析器在验证前修改了负载。
• Webhook 密钥与环境不匹配。
• 使用的不是原始请求体字节来计算摘要。

修复方法：

• 使用原始请求体字节进行验证。
• 确保使用完全匹配的已配置密钥进行 HMAC SHA-256 计算。
• 确认密钥属于同一商户/环境。

验证：

• 重放的负载和实时沙盒 Webhook 均能通过签名验证。

结账/会话有效期已过

症状：

• 延迟后支付尝试失败、结账状态过期，或流程超时。

可能原因：

• 结账在待处理状态停留超过有效期。
• 前端使用已过期的结账 ID 重试。

修复方法：

• 每次重试都创建新的结账。
• 添加前端超时处理，在超时后请求新的结账。

验证：

• 重试流程始终使用新的结账 ID/引用，并在沙盒中成功。

未激活所需权限范围或身份验证不匹配

症状：

• 凭据有效，但仍收到 401/403 响应。

可能原因：

• 缺少 payments 或其他必需的权限范围。
• 在需要 OAuth 的场景中使用了 API 密钥，或反之。

修复方法：

• 确认集成类型所使用的身份验证模式。
• 根据需要申请/启用所需权限范围，并重新签发令牌/密钥。

验证：

• 之前失败的端点使用权限最小化的有效凭据后能够成功。

货币与商户不匹配

症状：

• 结账因货币或商户限制而被拒绝。

可能原因：

• 商户未启用结账所用的货币。
• 在多商户场景中选择了错误的商户。

修复方法：

• 创建结账前验证商户和货币。
• 在后端验证层强制执行映射规则。

验证：

• 无效组合会被提前拦截；有效组合可以正常处理。

Affiliate 密钥/应用标识符不匹配

症状：

• 刷卡流程失败或无法正确初始化。

可能原因：

• Bundle ID/应用 ID 与 Affiliate 密钥配置不匹配。
• 刷卡请求中缺少 Affiliate 元数据。

修复方法：

• 使应用标识符与 Affiliate 密钥设置保持一致。
• 在终端/云端流程中包含必需的 Affiliate 数据。

验证：

• 设备/读卡器结账流程能在沙盒/测试设备中初始化并完成。

checkout_reference 重复

症状：

• 结账结果重复或冲突，导致对账混乱。

可能原因：

• 生成的引用不唯一。
• 重试逻辑在没有幂等性保护的情况下重用了过期引用。

修复方法：

• 为每个逻辑支付意图生成唯一且确定性的引用。
• 添加重复检测和安全重试行为。

验证：

• 重复尝试会被拒绝或妥善对账，不会导致重复履约。

卡片组件被阻止或未挂载

症状：

• 组件无法呈现，或发出 error/初始化失败。

可能原因：

• CSP 或域策略阻止了脚本加载。
• 结账 ID 无效或环境不匹配。
• 前端初始化存在竞态条件。

修复方法：

• 在 CSP 和 JS 来源配置中允许所需的 SumUp 脚本来源。
• 确认结账 ID 对应的环境及其生命周期。
• 仅在脚本加载完成且 DOM 就绪后挂载。

验证：

• 组件能够稳定挂载并完成测试支付。

必需的回复规范

对于每个调试答复，请包含：

1. 按置信度排序的最可能根本原因。
2. 用于确认或排除每个假设的最小复现检查。
3. 确切的修复步骤及低风险的发布建议。
4. 修复后的验证清单。
5. 防止问题再次发生的监控／日志改进。