Hyperswitch项目：如何集成新的支付连接器

张俊领Tilda

于 2025-06-01 09:16:50 发布

阅读量908

点赞数 20

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01194/article/details/148362712

Hyperswitch项目：如何集成新的支付连接器

hyperswitch juspay/hyperswitch: 这是一个用于实现API网关和微服务的Java库。适合用于需要实现API网关和微服务的场景。特点：易于使用，支持多种API网关和微服务实现，具有高性能和可扩展性。项目地址: https://gitcode.com/gh_mirrors/hy/hyperswitch

概述

在支付网关系统中，连接器(Connector)扮演着至关重要的角色，它负责与各种支付服务提供商(如Stripe、Adyen等)进行交互。本文将详细介绍如何在Hyperswitch项目中集成一个新的支付连接器，帮助开发者理解整个集成流程和技术实现细节。

准备工作

在开始集成前，需要确保满足以下条件：

熟悉目标连接器的API文档和规范
本地已搭建并运行Hyperswitch项目环境
获取测试用的API凭证(通常在连接器官网申请沙盒/UAT环境凭证)
安装Rust nightly工具链用于代码格式化：
```
rustup toolchain install nightly
```

核心概念解析

连接器(Connector)与支付方式(Payment Method)

连接器：处理支付交易或管理欺诈风险的中间件(如Stripe处理支付，Signifyd管理风险)
支付方式：具体的交易方式(如信用卡、PayPal等)

集成步骤详解

1. 生成连接器模板

使用项目提供的脚本快速生成连接器基础结构：

sh scripts/add_connector.sh <connector-name> <connector-base-url>

生成的文件结构示例：

hyperswitch_connectors/src/connectors
├── billwerk
│   └── transformers.rs
└── billwerk.rs
crates/router/tests/connectors
└── billwerk.rs

注意：需要将测试文件移动到正确位置： crates/hyperswitch_connectors/src/connectors/connector_name/test.rs → crates/router/tests/connectors/connector_name.rs

2. 实现请求和响应类型

在transformers.rs中定义API请求/响应结构体，并实现与Hyperswitch核心数据结构的转换。

请求结构体示例

#[derive(Debug, Serialize)]
pub struct BillwerkPaymentsRequest {
    handle: String,
    amount: MinorUnit,
    source: Secret<String>,
    currency: common_enums::Currency,
    customer: BillwerkCustomerObject,
    metadata: Option<SecretSerdeValue>,
    settle: bool,
}

转换实现

impl TryFrom<&BillwerkRouterData<&types::PaymentsAuthorizeRouterData>> for BillwerkPaymentsRequest {
    type Error = error_stack::Report<errors::ConnectorError>;
    fn try_from(item: &BillwerkRouterData<&types::PaymentsAuthorizeRouterData>) -> Result<Self, Self::Error> {
        // 转换逻辑...
    }
}

3. 处理响应映射

定义支付状态枚举并实现到Hyperswitch状态的转换：

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum BillwerkPaymentState {
    Created,
    Authorized,
    Pending,
    Settled,
    Failed,
    Cancelled,
}

impl From<BillwerkPaymentState> for enums::AttemptStatus {
    fn from(item: BillwerkPaymentState) -> Self {
        match item {
            BillwerkPaymentState::Created | BillwerkPaymentState::Pending => Self::Pending,
            BillwerkPaymentState::Authorized => Self::Authorized,
            BillwerkPaymentState::Settled => Self::Charged,
            BillwerkPaymentState::Failed => Self::Failure,
            BillwerkPaymentState::Cancelled => Self::Voided,
        }
    }
}

4. 关键字段说明

connector_request_reference_id：商户请求参考ID
connector_response_reference_id：连接器返回的交易标识ID
resource_id：连接器交易ID
redirection_data：用于3D Secure等重定向流程

5. 错误处理

定义错误响应结构体：

#[derive(Debug, Serialize, Deserialize)]
pub struct BillwerkErrorResponse {
    pub code: Option<i32>,
    pub error: String,
    pub message: Option<String>,
}

核心Trait实现

ConnectorCommon Trait

包含连接器的基本描述信息：

impl ConnectorCommon for Billwerk {
    fn id(&self) -> &'static str {
        "Billwerk"
    }
    
    fn get_currency_unit(&self) -> api::CurrencyUnit {
        api::CurrencyUnit::Minor
    }
    
    fn common_get_content_type(&self) -> &'static str {
        "application/json"
    }
    
    // 其他必要方法...
}

ConnectorIntegration Trait

实现各API端点的集成逻辑：

impl ConnectorIntegration<api::Authorize, ...> for Billwerk {
    fn get_url(&self, _req: &..., connectors: &Connectors) -> CustomResult<String, ...> {
        Ok(format!("{}/v1/payments", self.base_url(connectors)))
    }
    
    fn get_request_body(&self, req: &...) -> CustomResult<RequestContent, ...> {
        let connector_req = BillwerkPaymentsRequest::try_from(req)?;
        Ok(RequestContent::Json(Box::new(connector_req)))
    }
    
    // 其他必要方法...
}