欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

Flutter 三方库 mpesa 的鸿蒙化适配指南 - 支持 Daraja API、集成 C2B/B2C 支付流与实时交易查询

前言

随着鸿蒙生态走向全球市场，支持国际化支付业务变得至关重要。mpesa 是肯尼亚及东非地区最主流的移动支付方式（由 Safaricom 提供）。通过 Flutter for OpenHarmony 的跨平台能力，开发者可以利用 mpesa 插件在鸿蒙应用中快速集成 Daraja API 支付功能。本文将详细讲解如何在鸿蒙端通过该库实现完整的支付闭环。

一、原理解析 / 概念介绍

1.1 基础原理

mpesa 库是对 Safaricom Daraja API 的 Dart 封装。它通过 RESTful 接口与 M-Pesa 支付网关通信。

graph LR
    A["鸿蒙 App (Flutter)"] --> B["mpesa 插件"]
    B -- "HTTPS (OAuth 2.0)" --> C["Safaricom Daraja API"]
    C -- "Push Notification" --> D["用户手机"]
    D -- "输入 PIN 码" --> C
    C -- "Callback" --> E["商户后台"]

1.2 核心优势

• 全场景支持：覆盖 C2B（消费者支付）、B2C（企业转账）、B2B 等核心业务。
• 内置安全认证：自动处理 OAuth 身份认证令牌的获取与刷新。
• 类型安全：支付请求和响应参数均有严格的模型定义。
• 轻量解耦：纯 Dart 逻辑，不涉及底层原生 SDK 冲突。

二、鸿蒙基础指导

2.1 适配情况

1. 是否原生支持？ 是，由于使用标准 HTTP 请求。
2. 是否鸿蒙官方支持？ 社区跨平台支持。
3. 是否需要安装额外的 package？ 不需要。

2.2 适配代码

在 pubspec.yaml 中配置：

dependencies:
  mpesa: ^2.0.0

鸿蒙环境注意：开发者必须在 module.json5 中确保开启了 ohos.permission.INTERNET 权限，以支持外网 API 访问。

三、核心 API / 组件详解

3.1 核心方法

方法	说明
Mpesa.init()	初始化配置（Consumer Key/Secret）
lipaNaMpesaOnline()	发起 STK Push 支付
c2bRegisterUrl()	注册 C2B 回调地址
getTransactionStatus()	查询历史交易状态

3.2 基础初始化

import 'package:mpesa/mpesa.dart';

void setupMpesa() {
  Mpesa.init(
    consumerKey: "YOUR_CONSUMER_KEY",
    consumerSecret: "YOUR_CONSUMER_SECRET",
    passKey: "YOUR_PASS_KEY",
    shortCode: "YOUR_BUSINESS_SHORT_CODE",
    environment: MpesaEnvironment.sandbox, // 测试环境
  );
}

四、典型应用场景

4.1 用户在线支付 (STK Push)

这是鸿蒙 App 中最常用的场景：用户点击支付，手机自动弹出输入 PIN 码窗口。

Future<void> payNow() async {
  try {
    final response = await Mpesa.instance.lipaNaMpesaOnline(
      phoneNumber: "2547XXXXXXXX",
      amount: 10,
      accountReference: "Order_001",
      transactionDesc: "购买鸿蒙开发教程",
      callbackUrl: "https://your-domain.com/callback",
    );
    print("鸿蒙端支付响应: ${response.customerMessage}");
  } catch (e) {
    print("支付发起失败: $e");
  }
}

4.2 余额查询 (B2C)

企业向个人转账，如发放佣金或退款。

Future<void> refundUser() async {
  final res = await Mpesa.instance.b2cPayment(
    phoneNumber: "2547XXXXXXXX",
    amount: 100,
    occasion: "退款服务",
    remarks: "鸿蒙系统兼容性优异",
    queueTimeOutURL: "https://your-domain.com/timeout",
    resultURL: "https://your-domain.com/result",
  );
  print("退款流水 ID: ${res.conversationID}");
}

五、OpenHarmony 平台适配挑战

5.1 网络延迟与超时

由于 M-Pesa 的服务器位于海外，在鸿蒙端发起请求时，可能会遇到网络不稳定的情况。建议将 Dart HTTP 客户端的 connectTimeout 设置在 30 秒以上，并配合 retry 策略。

5.2 回调处理

M-Pesa 支付成功后会向后端服务器发送通知。在鸿蒙端，应用需通过 EventChannel 或推送服务监听后端同步过来的支付结果，以确保 UI 状态的实时更新。

六、综合实战演示

import 'package:flutter/material.dart';
import 'package:mpesa/mpesa.dart';

class MpesaPayPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('鸿蒙端 M-Pesa 支付集成')),
      body: Center(
        child: ElevatedButton(
          style: ElevatedButton.styleFrom(backgroundColor: Colors.green),
          onPressed: () async {
            // 实现支付逻辑
            await Mpesa.instance.lipaNaMpesaOnline(
              phoneNumber: "254712345678",
              amount: 1,
              accountReference: "TestAPP",
              transactionDesc: "测试支付",
              callbackUrl: "https://callback.io",
            );
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text('支付请求已发送到您的手机，请检查！'))
            );
          },
          child: Text('使用 M-Pesa 支付', style: TextStyle(color: Colors.white)),
        ),
      ),
    );
  }
}

七、总结

通过 mpesa 插件，Flutter for OpenHarmony 应用能够无缝接入东非最大的移动货币系统。这不仅拓宽了鸿蒙应用的商业维度，也展示了鸿蒙生态极佳的跨国技术兼容性。开发者只需关注业务逻辑，复杂的加密认证交由插件处理即可。