Hyperswitch项目中Relay退款状态查询API的设计与实现

背景概述

在现代支付系统中，退款流程的透明度和可追溯性至关重要。Hyperswitch作为一个支付网关解决方案，需要处理各种复杂的支付场景，其中包括商户直接与支付处理器（如Stripe）完成支付后，再通过Hyperswitch发起退款的特殊情况。这种场景下，Hyperswitch需要提供一种机制来跟踪和管理这些"间接"退款的状态。

技术挑战

传统支付流程中，Hyperswitch会参与支付和退款的全生命周期管理。但在某些业务场景中，商户可能直接与支付处理器完成支付交易，仅通过Hyperswitch处理后续的退款操作。这种情况下，系统需要解决以下技术难题：

1. 如何在不掌握原始支付信息的情况下处理退款
2. 如何提供一致的API接口让商户查询退款状态
3. 如何保持系统数据与支付处理器状态的同步

解决方案设计

Hyperswitch团队设计了Relay API机制来解决上述问题，其核心思想是：

1. 请求转发：Relay API本质上是一个请求转发器，将商户的请求直接传递给支付处理器，不进行额外的业务逻辑处理
2. 状态跟踪：系统会记录这些转发操作的状态，建立基本的跟踪机制
3. 混合查询：提供结合本地存储和实时查询的混合状态获取方式

关键实现细节

退款状态查询API

新实现的Retrieve API提供了两种工作模式：

1. 基础查询模式：仅返回系统数据库中存储的Relay状态信息
2. 强制同步模式：当请求中带有force_sync=true参数时，如果本地状态非终态，API会主动调用支付处理器接口获取最新状态

数据流设计

整个流程的数据流转如下：

1. 商户直接与支付处理器完成支付交易，保存支付参考ID
2. 商户通过Hyperswitch发起退款，使用之前保存的支付参考ID
3. 商户通过Retrieve API查询退款状态

状态机设计

系统实现了完善的状态机来管理Relay操作的生命周期：

1. 初始状态：退款请求刚被接收
2. 处理中状态：请求已转发给支付处理器但未收到最终响应
3. 成功/失败终态：收到支付处理器的最终响应

技术优势

这种设计带来了几个显著优势：

1. 兼容性：支持各种支付处理器的不同API规范
2. 可观测性：即使对于间接处理的退款，也能提供状态跟踪
3. 灵活性：商户可以根据需要选择仅查询本地状态或强制获取最新状态
4. 性能优化：通过本地缓存减少对支付处理器的不必要查询

应用场景

这种机制特别适用于以下业务场景：

1. 商户逐步迁移支付流程到Hyperswitch的过程中
2. 需要支持多种支付处理器的混合环境
3. 对退款状态实时性要求不同的业务需求
4. 需要统一管理不同来源退款的企业系统

总结

Hyperswitch通过引入Relay退款状态查询API，巧妙地解决了混合支付环境下的退款管理难题。这种设计既保持了系统的简洁性，又提供了必要的灵活性和可扩展性，为商户提供了统一的退款管理接口，无论原始支付是否通过Hyperswitch完成。这种解决方案体现了现代支付系统设计中接口抽象和状态管理的最佳实践。