支付处理

本页概述 Genstore 与支付应用 在 账户授权、支付处理、退款、捕获、取消授权 五个环节中的交互原则与整体生命周期，并提供各子流程的详细指引。

角色与职责

• 商户：在 Genstore 后台发起授权、支付、退款、捕获、取消等操作。
• Genstore：转发请求、维护支付/退款状态，并在后台呈现最终结果。
• 支付 App：校验商户或用户输入、执行支付/退款逻辑，并通过回调 API 将最终结果异步告知 Genstore。

通用交互原则

• 异步回调：所有支付类操作必须通过支付 App 调用 Genstore 的 Update * result API 回传最终结果。
• 幂等与重试：每个请求都需支持幂等键和安全重试机制，确保网络异常下结果一致。
• 终态不可变：一旦结果更新为 成功 或 失败，不可再变更。
• 测试模式：支付 App 必须支持测试模式，当开启时，所有非查询类请求会在参数中附带 test: true。

支付生命周期概览

支付生命周期通常包括以下阶段：

1. 授权（Authorization）：商户账户与支付账户的绑定。
2. 支付处理（Processing）：发起支付请求，包括直连卡、3DS验证、站外支付等模式。
3. 捕获（Capture）：在"先授权后捕获"的模式下执行资金扣划。
4. 退款（Refund）：对已成功支付发起部分或全部退款。
5. 取消授权（Void）：撤销尚未捕获的授权支付。

开发与接入要点

• 必须实现的回调 API：
  • Update account authorization result
  • Update payment result
  • Update refund result
  • Update capture result（如支持授权）
  • Update cancel result（如支持取消授权）
• 安全要求：卡信息必须使用 Genstore 指定的 ECIES 加解密方案，并绑定上下文 AAD，防止混用攻击。
• 上线检查清单：
  • 提供测试账户及失败用例验证
  • 覆盖直连卡、3DS、站外支付等主要场景
  • 验证异常处理、幂等与重试机制
  • 确认权限范围仅限支付相关

开发建议

1. 错误处理：实现完善的错误处理机制，确保任何情况下都能返回明确的状态码和错误信息
2. 日志记录：记录所有关键操作和状态变更，便于问题排查和交易审计
3. 性能优化：优化响应时间，减少用户等待，提供流畅的支付体验
4. 状态管理：实现健壮的状态管理机制，确保支付生命周期状态转换的准确性