BudPay Inline Flutter Plugin #

A Flutter plugin that provides a seamless integration of BudPay's inline payment system for Android and iOS platforms. This plugin wraps the existing BudPay JavaScript inline payment solution within a WebView, allowing you to accept payments in your Flutter applications with ease.

Features #

Cross-Platform Support: Works seamlessly on both Android and iOS platforms.
Easy Integration: Simple and straightforward API to initiate payments.
Customizable: Supports customization options such as custom fields, callback URLs, and more.
Error Handling: Provides callbacks for success, error, and cancellation events.
Secure: Uses BudPay's secure payment infrastructure.

Installation #

Add the following to your project's pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  budpay_inline_flutter: ^0.0.1  # Replace with the latest version

Replace ^0.0.1 with the latest version of the plugin as specified on pub.dev.

Then run:

flutter pub get

Getting Started #

To start using the plugin:

Import the Package:

import 'package:budpay_inline_flutter/budpay_inline_flutter.dart';

Initialize Payment Parameters:

Prepare the necessary parameters required by BudPay, such as publicKey, email, amount, etc.
Initiate the Payment:

Use the BudpayInlinePayment widget to initiate the payment process.

Usage #

Here's a step-by-step guide to using the budpay_inline_flutter plugin in your Flutter application.

1. Import the Plugin #

import 'package:budpay_inline_flutter/budpay_inline_flutter.dart';

2. Prepare Payment Information #

Collect or define the necessary payment information:

Public Key: Obtain your public key from your BudPay dashboard.
Customer Details: Email, first name, last name, etc.
Transaction Details: Amount, currency, reference, etc.

3. Create the Payment Widget #

Use the BudpayInlinePayment widget to initiate the payment process.

BudpayInlinePayment(
  publicKey: 'YOUR_PUBLIC_KEY',
  email: 'customer@example.com',
  amount: '1000',
  firstName: 'John',
  lastName: 'Doe',
  currency: 'NGN',
  reference: 'unique_transaction_reference',
  onSuccess: (response) {
    // Handle successful payment here
    print('Payment successful: $response');
  },
  onError: (error) {
    // Handle error here
    print('Payment error: $error');
  },
  onCancel: () {
    // Handle cancellation here
    print('Payment cancelled by user');
  },
  customFields: {
    'custom_field_1': 'value1',
    'custom_field_2': 'value2',
  },
)

4. Navigate to the Payment Screen #

You can navigate to a new screen to display the payment widget.

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (context) => BudpayInlinePayment(
      // ... parameters ...
    ),
  ),
);

API Reference #

BudpayInlinePayment #

A widget that initiates the BudPay inline payment process.

Constructor Parameters

Parameter	Type	Required	Description
`publicKey`	`String`	Yes	Your BudPay public key.
`email`	`String`	Yes	Customer's email address.
`amount`	`String`	Yes	Amount to be charged (as a string).
`firstName`	`String?`	No	Customer's first name.
`lastName`	`String?`	No	Customer's last name.
`currency`	`String`	Yes	Currency code (e.g., `NGN`, `USD`).
`reference`	`String?`	No	Unique transaction reference. If not provided, BudPay will generate one.
`logoUrl`	`String?`	No	URL to your custom logo to display in the payment popup.
`callbackUrl`	`String?`	No	URL for BudPay to send payment notifications.
`customFields`	`Map<String, dynamic>?`	No	Additional custom fields as key-value pairs.
`onSuccess`	`Function(dynamic)`	Yes	Callback function invoked on successful payment.
`onError`	`Function(dynamic)`	Yes	Callback function invoked when an error occurs.
`onCancel`	`Function()`	Yes	Callback function invoked when the payment is canceled by the user.

Platform-specific Setup #

Android #

1. Internet Permission

Add the following permission to your app's AndroidManifest.xml file to allow network access:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.your_app">
    <!-- Add this line -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- Existing content -->
</manifest>

2. WebView Initialization (Optional)

If you encounter issues with the WebView on Android, you can specify the WebView implementation:

import 'dart:io';
import 'package:webview_flutter/webview_flutter.dart';

@override
void initState() {
  super.initState();

  if (Platform.isAndroid) {
    WebView.platform = AndroidWebView();
  }

  // Rest of your initialization code
}

iOS #

1. App Transport Security Settings

To allow your app to load web content, update the Info.plist file:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

2. WKWebView Configuration (Optional)

Ensure that the WebView is properly configured in your Flutter project. In most cases, the default configuration is sufficient.

Permissions #

Ensure the following permissions are set:

Android: Internet access (android.permission.INTERNET).
iOS: Network access configurations in Info.plist.

Error Handling #

Implement the onError callback to handle errors during the payment process.

onError: (error) {
  // Handle error
  print('Payment error: $error');
}

Possible error scenarios:

Network issues.
Payment failures.
Unexpected responses.

Ensure that you provide meaningful feedback to the user and handle errors gracefully.

Important Notes #

Test Mode vs. Live Mode: Use your BudPay test public key for testing and switch to the live public key for production.
Currency: Ensure that the currency code you provide is supported (NGN, GHS, USD, etc.).
Amount Format: The amount parameter should be a string representing the amount in the smallest currency unit (e.g., kobo for NGN).
Platform Support: This plugin supports Android and iOS platforms. Web and desktop platforms are not supported.
WebView Content: The plugin uses a WebView to load BudPay's inline payment JavaScript. Ensure that your app allows WebView content to execute JavaScript.

Troubleshooting #

WebView Not Displaying #

Ensure that all required permissions are set.
Check for any errors in the console.
Verify network connectivity.

Payment Not Processing #

Confirm that your public key is correct.
Ensure that the amount and other parameters are valid.
Check BudPay's service status.

Error Messages #

Implement comprehensive error handling.
Log errors for debugging purposes.
Provide user-friendly error messages.

Contributing #

Contributions are welcome! Please follow these steps:

Fork the Repository:

Click the "Fork" button at the top right corner of the repository page.
Create a New Branch:
```
git checkout -b feature/your-feature
```
Commit Your Changes:
```
git commit -am 'Add a feature'
```
Push to the Branch:
```
git push origin feature/your-feature
```
Open a Pull Request:

Go to the repository on GitHub and click "Compare & pull request".

License #

This project is licensed under the MIT License.

For any issues or questions, please create an issue on the GitHub repository.

Contact #

If you have any questions or need support, please contact:

Email: developers@budpay.com
GitHub: https://github.com/okeybudpay

Changelog #

Please see the Changelog for more information on version updates.

Additional Resources #

BudPay Documentation: https://devs.budpay.com/
Flutter WebView Documentation: https://pub.dev/packages/webview_flutter
Flutter Documentation: https://flutter.dev/docs

Thank you for using budpay_inline_flutter! We hope it makes integrating BudPay payments into your Flutter app easier. Happy coding!

budpay_inline_flutter 0.0.2 budpay_inline_flutter: ^0.0.2 copied to clipboard

Metadata