buzapay_sdk 0.1.0

Flutter SDK for Buzapay Payment Gateway. Accept payments with Card, Bank Transfer, USSD, and Stablecoins (USDT/USDC).

Buzapay Flutter SDK

A Flutter SDK for integrating Buzapay Payment Gateway. Accept payments seamlessly with multiple payment methods.

Features

• Multiple Payment Methods - Card, Bank Transfer, USSD, Stablecoins (USDT/USDC)
• Pre-built UI Components - Ready-to-use checkout button and WebView
• Cross-Platform - iOS, Android, macOS, Windows, Linux and Web support
• Secure - Built-in signature generation and token management

Installation

Add buzapay_sdk to your pubspec.yaml:

dependencies:
  buzapay_sdk: ^0.1.0

Then run:

flutter pub get

Platform Setup

Android

Add internet permission to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>

iOS

No additional setup required.

Quick Start

1. Initialize the SDK

Initialize Buzapay in your app's main() function:

import 'package:buzapay_sdk/buzapay_sdk.dart';

void main() {
  Buzapay.initialize(
    config: BuzapayConfig(
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
      merchantId: 'YOUR_MERCHANT_ID',
      environment: BuzapayEnvironment.sandbox, // Use .production for live
      enableLogging: true, // Set to false in production
    ),
  );
  
  runApp(MyApp());
}

2. Accept Payments

Option A: One-liner Checkout

The simplest way to accept payments:

final result = await Buzapay.instance.checkout(
  context: context,
  amount: 5000,           // Amount in minor units (₦50.00)
  currency: 'NGN',
  email: '[e-mail]',
  phoneNumber: '08012345678',
  redirectUrl: 'https://yourapp.com/callback',
  onSuccess: (reference) {
    print('Payment successful! Reference: $reference');
    // Grant value to customer
  },
  onError: (error) {
    print('Payment failed: ${error.message}');
  },
  onCancel: () {
    print('User cancelled payment');
  },
);

Option B: Pre-built Checkout Button

Drop-in button widget:

BuzapayCheckoutButton(
  amount: 5000,
  currency: 'NGN',
  email: '[e-mail]',
  phoneNumber: '08012345678',
  redirectUrl: 'https://yourapp.com/callback',
  generatePaymentLink: (request) => Buzapay.instance.generatePaymentLink(
    email: request.email,
    phoneNumber: request.phoneNumber,
    merchantReference: request.merchantReference,
    amount: request.amount,
    currency: request.currency,
    redirectUrl: request.redirectUrl,
  ),
  onSuccess: (reference) => print('Success: $reference'),
  onError: (error) => print('Error: ${error.message}'),
  buttonText: 'Pay ₦50.00',
)

Option C: Manual Flow (Advanced)

For full control over the payment flow:

// 1. Generate payment link
final response = await Buzapay.instance.generatePaymentLink(
  email: '[e-mail]',
  phoneNumber: '08012345678',
  merchantReference: 'ORDER_123',
  amount: '5000',
  currency: 'NGN',
  narration: 'Order #123 payment',
  redirectUrl: 'https://yourapp.com/callback',
);

// 2. Open in WebView
if (response.isSuccessful) {
  Navigator.push(
    context,
    MaterialPageRoute(
      builder: (_) => BuzapayWebView(
        url: response.launchUrl!,
        redirectUrl: 'https://yourapp.com/callback',
        onSuccess: (ref) => handleSuccess(ref),
        onError: (e) => handleError(e),
      ),
    ),
  );
}

Configuration

BuzapayConfig Options

Parameter	Type	Required	Description
clientId	String	✅	Your Buzapay client ID
clientSecret	String	✅	Your Buzapay client secret
merchantId	String	✅	Your Buzapay merchant ID
environment	BuzapayEnvironment	❌	sandbox (default) or production
timeout	Duration	❌	Request timeout (default: 30s)
enableLogging	bool	❌	Enable debug logs (default: false)
verboseLogging	bool	❌	Enable detailed HTTP logs (default: false)

Supported Currencies

Currency	Description
NGN	Nigerian Naira
USD	US Dollar

Error Handling

The SDK provides typed exceptions for different error scenarios:

try {
  await Buzapay.instance.checkout(...);
} on BuzapayAuthException catch (e) {
  // Invalid credentials or expired token
  print('Auth error: ${e.message}');
} on BuzapayNetworkException catch (e) {
  // Network connectivity issues
  print('Network error: ${e.message}');
} on BuzapayPaymentException catch (e) {
  // Payment processing failed
  print('Payment error: ${e.message} (code: ${e.code})');
} on BuzapayValidationException catch (e) {
  // Invalid input data
  print('Validation error: ${e.message}');
} on BuzapayCancelledException catch (e) {
  // User cancelled
  print('Cancelled');
}

Webhooks

For production use, always verify payments server-side using webhooks. Buzapay sends webhook notifications for:

• Card payments
• Bank transfers (NGN)
• Stablecoin payments

See Buzapay Webhook Documentation for setup instructions.

Example App

Check out the complete example in the /example directory:

cd example
flutter run

API Reference

Buzapay

Method	Description
Buzapay.initialize(config)	Initialize the SDK
Buzapay.instance	Get the SDK singleton
checkout(...)	Open checkout WebView
generatePaymentLink(...)	Generate payment link URL

Models

• BuzapayConfig - SDK configuration
• PaymentLinkRequest - Payment link request data
• PaymentLinkResponse - Payment link response with launchUrl
• PaymentResult - Checkout result enum (success, failed, cancelled)

Security Best Practices

1. Never expose credentials - Keep clientSecret secure, ideally on your backend
2. Verify webhooks - Always verify payment status server-side
3. Use HTTPS - Ensure your redirectUrl uses HTTPS
4. Production mode - Set environment: BuzapayEnvironment.production for live payments

Support

• Documentation
• Report Issues
• Contact Support

License

MIT License - see LICENSE for details.