buzapay_sdk 0.2.0

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

Buzapay Flutter SDK

A Flutter SDK for integrating Buzapay Payment Gateway. Accept payments seamlessly in NGN and USD (stablecoins).

Features

• Accept NGN & USD - Nigerian Naira and USD stablecoin payments
• Simple Integration - Just your Merchant ID, no secret keys client-side
• Pre-built UI - Ready-to-use checkout button and WebView
• Cross-Platform - iOS, Android, macOS, Windows and Linux support

Installation

Add buzapay_sdk to your pubspec.yaml:

dependencies:
  buzapay_sdk: ^0.2.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 with your Merchant ID:

import 'package:buzapay_sdk/buzapay_sdk.dart';

void main() {
  Buzapay.initialize(
    config: BuzapayConfig(
      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',
  onComplete: (reference) {
    // The SDK does NOT determine payment success/failure.
    // Always verify the transaction server-side using the reference.
    print('Checkout done. Reference: $reference');
  },
);

if (result == PaymentResult.dismissed) {
  print('User left the checkout');
}

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,
  ),
  onComplete: (reference) {
    // Verify the transaction server-side
    print('Checkout done. Reference: $reference');
  },
  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',
        onComplete: (reference) {
          // Verify the transaction server-side
        },
      ),
    ),
  );
}

Configuration

BuzapayConfig Options

Parameter	Type	Required	Description
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 (stablecoins)

Error Handling

The SDK provides typed exceptions for different error scenarios:

try {
  await Buzapay.instance.checkout(...);
} on BuzapayAuthException catch (e) {
  // Invalid or unrecognized merchant ID
  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}');
}

Webhooks

For production use, always verify payments server-side using webhooks.

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 (merchant ID + environment)
• PaymentLinkRequest - Payment link request data
• PaymentLinkResponse - Payment link response with launchUrl
• PaymentResult - Checkout flow result enum (completed, dismissed)

Security

1. No secret keys client-side - The SDK only uses your Merchant ID
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.