Flutter支付功能插件paychangu_flutter的使用

PayChangu Flutter SDK

一个用于将PayChangu支付网关集成到Flutter应用程序中的SDK。该SDK提供了一种简单且安全的方式来接受通过多种支付方式（包括Airtel Money、TNM Mpamba和信用卡）进行的付款。

特性

• 🔒 安全的支付处理
• 💳 多种支付方式支持
• 🌐 基于WebView的结账体验
• ✨ 简单的集成
• 🔄 实时支付状态更新
• ⚡ 异步支付处理
• 🛠️ 可定制的UI元素
• ✅ 交易验证

开始使用

前提条件

• Flutter SDK
• PayChangu商户账户和API凭证
• 最低Flutter版本: 1.17.0
• Dart SDK: ^3.5.4

安装

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

dependencies:
  paychangu_flutter: ^0.0.1

然后运行以下命令：

flutter pub get

使用方法

1. 初始化PayChangu

import 'package:paychangu_flutter/paychangu_flutter.dart';

final config = PayChanguConfig(
  secretKey: 'your_secret_key_here',
  isTestMode: true, // 生产环境设置为false
);

final paychangu = PayChangu(config);

2. 创建支付请求

final request = PaymentRequest(
  txRef: 'unique_transaction_reference', // 唯一的交易参考
  firstName: 'John', // 名字
  lastName: 'Doe', // 姓氏
  email: 'john@example.com', // 邮箱
  currency: Currency.MWK, // 货币类型
  amount: 1000, // 金额
  callbackUrl: 'https://your-domain.com/callback', // 回调URL
  returnUrl: 'https://your-domain.com/return', // 返回URL
);

3. 启动支付

Widget buildPaymentWidget() {
  return paychangu.launchPayment(
    request: request,
    onSuccess: (response) {
      print('Payment successful: $response');
      // 成功后验证交易
      verifyTransaction(response['tx_ref']);
    },
    onError: (error) {
      print('Payment failed: $error');
    },
    onCancel: () {
      print('Payment cancelled');
    },
  );
}

4. 验证交易

始终在服务器端验证交易，然后再向客户提供价值：

Future<void> verifyTransaction(String txRef) async {
  try {
    // 验证交易
    final verification = await paychangu.verifyTransaction(txRef);
    
    // 验证支付详情
    final isValid = paychangu.validatePayment(
      verification,
      expectedTxRef: txRef,
      expectedCurrency: 'MWK',
      expectedAmount: 1000,
    );
    
    if (isValid) {
      // 支付有效，向客户提供价值
      print('Payment verified successfully');
      print('Amount paid: ${verification.data.amount}');
      print('Payment channel: ${verification.data.authorization.channel}');
      print('Transaction reference: ${verification.data.txRef}');
    } else {
      // 支付验证失败
      print('Payment validation failed');
    }
  } on PayChanguException catch (e) {
    print('Verification failed: ${e.message}');
    if (e.details != null) {
      print('Error details: ${e.details}');
    }
  }
}

完整示例

这是一个实现支付和验证的完整示例：

class PaymentScreen extends StatelessWidget {
  final paychangu = PayChangu(
    PayChanguConfig(
      secretKey: 'your_secret_key_here',
      isTestMode: true,
    ),
  );

  Future<void> _handlePaymentSuccess(Map<String, dynamic> response) async {
    try {
      final verification = await paychangu.verifyTransaction(response['tx_ref']);
      final isValid = paychangu.validatePayment(
        verification,
        expectedTxRef: response['tx_ref'],
        expectedCurrency: 'MWK',
        expectedAmount: 1000,
      );

      if (isValid) {
        // 处理成功的支付
        print('Payment verified: ${verification.data.amount} ${verification.data.currency}');
      }
    } catch (e) {
      print('Verification failed: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Payment')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            final request = PaymentRequest(
              txRef: 'tx-${DateTime.now().millisecondsSinceEpoch}', // 生成唯一的交易参考
              firstName: 'John',
              lastName: 'Doe',
              email: 'john@example.com',
              currency: Currency.MWK,
              amount: 1000,
              callbackUrl: 'https://your-domain.com/callback',
              returnUrl: 'https://your-domain.com/return',
            );

            Navigator.of(context).push(
              MaterialPageRoute(
                builder: (context) => Scaffold(
                  body: paychangu.launchPayment(
                    request: request,
                    onSuccess: _handlePaymentSuccess,
                    onError: (error) => print('Payment failed: $error'),
                    onCancel: () => print('Payment cancelled'),
                  ),
                ),
              ),
            );
          },
          child: Text('Pay Now'),
        ),
      ),
    );
  }
}

验证响应数据

验证响应包含详细的交易信息：

verification.data.status         // 交易状态
verification.data.amount        // 支付金额
verification.data.currency      // 使用的货币
verification.data.txRef         // 交易参考
verification.data.authorization.channel    // 使用的支付渠道
verification.data.authorization.provider   // 支付提供商
verification.data.customer      // 客户信息
verification.data.createdAt     // 交易创建时间

错误处理

SDK 提供了一个自定义的 PayChanguException 类来进行错误处理：

try {
  final verification = await paychangu.verifyTransaction(txRef);
} on PayChanguException catch (e) {
  print('Error: ${e.message}');
  if (e.details != null) {
    print('Details: ${e.details}');
  }
}