Flutter非官方插件chapa_unofficial的功能使用

chapa_unofficial 是一个用于Flutter应用程序中集成Chapa支付网关的库。它提供了方便的方法来初始化支付和验证支付状态。

功能

• 初始化支付流程
• 验证支付状态
• 应用内支付集成（WebView）
• 生成交易参考号

安装

在你的 pubspec.yaml 文件中添加以下行：

dependencies:
   chapa_unofficial: ^0.0.5

设备兼容性

虽然不是强制性的，但我们建议尽量减少在模拟器上使用此包。模拟器可能会引入未预见的错误或差异，影响包的性能和行为。

使用方法

1. 导入包

在你的Dart文件中导入包：

import 'package:chapa_unofficial/chapa_unofficial.dart';

2. 配置Chapa

通过调用带有你的私钥的 configure 方法来配置Chapa：

void main() {
  // setup chapa 
  Chapa.configure(privateKey: "CHASECK_TEST-HlZh7Xo8vNvT2jm6j08OzcnFnB63Yauf");
  runApp(const MyApp());
}

注意：Chapa类遵循单例模式，确保在整个应用中只创建并使用一个Chapa实例。你可以通过 Chapa.getInstance getter访问Chapa实例。

3. 初始化支付

使用 startPayment 方法初始化支付：

Future<void> pay() async {
  String? paymentUrl = await Chapa.getInstance.startPayment(
    context: context,
    onInAppPaymentSuccess: (successMsg) {
      // 处理成功事件
    },
    onInAppPaymentError: (errorMsg) {
      // 处理错误
    },
    amount: '1000',
    currency: 'ETB',
    txRef: 'GENERATED_TRANSACTION_REFERENCE',
  );
}

示例：

String? paymentUrl = await Chapa.getInstance.startPayment(
  enableInAppPayment: false,
  amount: '1000',
  currency: 'ETB',
);

必需参数：

• amount (String)：支付金额。
• currency (String)：支付货币。

可选参数：

• txRef (String)：支付交易参考号。如果没有传递，将生成默认的以 ‘test’ 为前缀的txRef。
• context (BuildContext)：用于导航的BuildContext。（如果 enableInAppPayment 设置为 true，则需要）。
• enableInAppPayment (bool)：决定是否使用应用内支付的标志。默认是 true。如果设置为 true，你需要传递上下文。
• onInAppPaymentSuccess (Function)：应用内支付成功时调用的回调函数。
• onInAppPaymentError (Function)：应用内支付出错时调用的回调函数。
• email (String)：与支付关联的电子邮件地址。
• firstName (String)：付款人的名字。
• lastName (String)：付款人的姓氏。
• title (String)：支付的标题或名称。
• description (String)：关于支付的附加描述或详细信息。
• phoneNumber (String)：与支付关联的电话号码。
• callbackUrl (String)：处理支付回调或通知的回调URL。
• returnUrl (String)：支付完成后重定向的返回URL。

4. 验证支付状态

使用 verifyPayment 方法验证支付状态：

Future<void> verify() async {
  Map<String, dynamic> verificationResult = await Chapa.getInstance.verifyPayment(
    txRef: 'GENERATED_TRANSACTION_REFERENCE',
  );
}

5. 重置配置

如果你需要重置配置，可以使用 resetConfiguration 方法：

Future<void> resetChapa() {
  Chapa.resetConfiguration();
}

交易参考生成器

TxRefRandomGenerator 类用于生成交易参考号。这个类使用UUID生成随机交易参考号，因此几乎不会出现重复的情况。

示例

Future<void> pay() async {
  // 生成带自定义前缀的随机交易参考号
  String txRef = TxRefRandomGenerator.generate(prefix: 'Pharmabet');
  
  // 访问生成的交易参考号
  String storedTxRef = TxRefRandomGenerator.gettxRef;
  
  // 打印生成的交易参考号和存储的交易参考号
  print('Generated TxRef: $txRef');
  print('Stored TxRef: $storedTxRef');
  
  await Chapa.getInstance.startPayment(
    context: context,
    onInAppPaymentSuccess: (successMsg) {
      // 处理成功事件
    },
    onInAppPaymentError: (errorMsg) {
      // 处理错误
    },
    amount: '1000',
    currency: 'ETB',
    txRef: storedTxRef,
  );
}

异常处理

chapa_unofficial 包提供了几种在支付过程中可能抛出的异常。这些异常允许你处理特定的错误场景，并向用户提供有意义的反馈。

• AuthException：当支付过程中发生认证错误时抛出。
• InitializationException：当 startPayment 方法出现问题时抛出。
• NetworkException：当支付过程中发生网络相关错误时抛出。
• ServerException：当支付过程中服务器端发生错误时抛出。
• UnknownException：当支付过程中发生未知或意外错误时抛出。
• VerificationException：当支付验证过程中发生错误时抛出。

示例

Example 1: 在 startPayment 中可能出现的异常

try {
  // start Payment Code 
} on ChapaException catch (e) {
  if (e is AuthException) {
    // 处理认证错误
  } else if (e is InitializationException) {
    // 处理初始化错误
  } else if (e is NetworkException) {
    // 处理网络错误
  } else if (e is ServerException) {
    // 处理服务器端错误
  } else {
    // 处理未知错误
  }
}

Example 2: 在 verifyPayment 中可能出现的异常

try {
  // verification code here 
} on ChapaException catch (e) {
  if (e is AuthException) {
    // 处理认证错误
  } else if (e is NetworkException) {
    // 处理网络错误
  } else if (e is ServerException) {
    // 处理服务器端错误
  } else if (e is VerificationException) {
    // 处理支付验证错误
  } else {
    // 处理未知错误 
  }
}

文档

有关如何使用Chapa的更多详情，请查看 API文档。

贡献

欢迎贡献！如果你遇到任何问题或有改进建议，请提交问题或拉取请求。

示例Demo

以下是一个完整的示例代码，展示如何使用 chapa_unofficial 包进行支付和验证操作：

import 'package:chapa_unofficial/chapa_unofficial.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void main() async {
  // setup chapa
  Chapa.configure(privateKey: "CHASECK_TEST-HlZh7Xo8vNvT2jm6j08OzcnFnB63Yauf");
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  Future<void> verify() async {
    Map<String, dynamic> verificationResult =
        await Chapa.getInstance.verifyPayment(
      txRef: TxRefRandomGenerator.gettxRef,
    );
    if (kDebugMode) {
      print(verificationResult);
    }
  }

  Future<void> pay() async {
    try {
      // Generate a random transaction reference with a custom prefix
      String txRef = TxRefRandomGenerator.generate(prefix: 'linat');

      // Access the generated transaction reference
      String storedTxRef = TxRefRandomGenerator.gettxRef;

      // Print the generated transaction reference and the stored transaction reference
      if (kDebugMode) {
        print('Generated TxRef: $txRef');
        print('Stored TxRef: $storedTxRef');
      }
      await Chapa.getInstance.startPayment(
        context: context,
        onInAppPaymentSuccess: (successMsg) {
          // Handle success events
        },
        onInAppPaymentError: (errorMsg) {
          // Handle error
        },
        amount: '1000',
        currency: 'ETB',
        txRef: storedTxRef,
      );
    } catch (e) {
      if (kDebugMode) {
        print(e);
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Linat's payment"),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'pay to linat416',
            ),
            TextButton(
                onPressed: () async {
                  await pay();
                },
                child: const Text("Pay")),
            TextButton(
                onPressed: () async {
                  await verify();
                },
                child: const Text("Verify")),
          ],
        ),
      ),
    );
  }
}