Skip to main content

​
Overview

The Novac Flutter plugin is the official plugin for the Novac Payment Gateway. It enables you to accept payments directly within your Flutter apps with support for cards, bank transfers, and mobile money — all with a customizable, secure checkout UI.

​
Prerequisites

See details

Before you begin, ensure that you’ve completed the following steps:
  • Obtain your API keys: required for making authenticated API calls.
  • A Flutter project with a minimum iOS version of 12.0 and minimum Android SDK version of 21
  • A Novac account with dashboard access

​
Installation

1

Add the Dependency

Add the plugin to your pubspec.yaml file:
    dependencies:
      novac_payment_plugin: ^1.0.0
2

Install the Package

Run the following command in your terminal to fetch the package:
    flutter pub get

​
Platform Setup

Because the SDK uses a webview for checkout, both iOS and Android need a URL scheme registered so that users are redirected back to your app after payment completes.

​
iOS

Add the following to your ios/Runner/Info.plist. This registers a custom URL scheme that the payment gateway uses to deep link back into your app: 
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourappscheme</string>
    </array>
  </dict>
</array>

​
Android

Add the following intent filter inside the relevant <activity> block in your android/app/src/main/AndroidManifest.xml. This tells Android to route the payment redirect back to your app: 
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourappscheme" />
</intent-filter>
Replace yourappscheme on both platforms with the same unique scheme. This value should also match whatever redirect URL is configured in your Novac dashboard.

​
Initialize the SDK

Before launching any payment, call NovacPaymentPlugin.initialize() once. Typically, at app startup or before your first checkout. This authenticates your app with Novac and optionally applies a custom theme to the checkout UI. 
import 'package:novac_payment_plugin/novac_payment_plugin.dart';

await NovacPaymentPlugin.initialize(
  apiKey: 'your_api_key',
  primaryColor: '#007AFF',      // Optional: Customize theme
  backgroundColor: '#FFFFFF',   // Optional
  buttonTextColor: '#FFFFFF',   // Optional
);

​
Launch the Checkout Flow

Once the SDK is initialized, call launchCheckout() to start a payment. The method is asynchronous and returns a PaymentResult object you can inspect to determine what happened. 
final result = await NovacPaymentPlugin.launchCheckout(
  amount: 5000,                 // Amount in smallest currency unit
  currency: 'NGN',
  redirectUrl: 'https://yourapp.com/payment-complete',
  customerData: CustomerData(
    email: 'customer@example.com',
    firstName: 'John',
    lastName: 'Doe',            // Optional
    phoneNumber: '+2348012345678', // Optional
  ),
  customizationData: CustomizationData(
    logoUrl: 'https://yourcompany.com/logo.png',
    paymentDescription: 'Payment for Order #12345',
    checkoutModalTitle: 'Complete Payment',
  ),
  transactionReference: 'unique-reference-123', // Optional: Auto-generated if not provided
);

// Handle the result
if (result.isSuccess) {
  print('Payment successful! Transaction ID: ${result.transactionId}');
} else if (result.isCancelled) {
  print('Payment cancelled by user');
} else {
  print('Payment failed: ${result.errorMessage}');
}
Customer’s Data This controls customer information.
​
customerData
Object
Customer’s Data This Controls the visual appearance and copy shown on the checkout modal.
​
CustomizationData
Object
The object returned by launchCheckout(). Check its properties to determine the outcome of the payment.
​
PaymentResult
Object

​
Verify a Payment

After a successful checkout, you can independently verify the transaction status on your backend or client using verifyPayment(). Pass the transaction reference returned from the checkout result: 
final verification = await NovacPaymentPlugin.verifyPayment('transaction-reference');

print('Status: ${verification.status}');
print('Amount: ${verification.amount}');
print('Currency: ${verification.currency}');
The object returned by verifyPayment(). Use this to confirm a transaction’s final status.
​
VerificationResult
Object

​
Error Handling

Wrap your checkout call in a try/catch block to handle both expected payment outcomes (failure, cancellation) and unexpected runtime errors gracefully: 
try {
  final result = await NovacPaymentPlugin.launchCheckout(...);
  
  if (result.isSuccess) {
    // Handle success
  } else if (result.isCancelled) {
    // Handle cancellation
  } else {
    // Handle failure
    print('Error: ${result.errorCode} - ${result.errorMessage}');
  }
} catch (e) {
  // Handle unexpected errors
  print('Unexpected error: $e');
}
Keep the following in mind when testing:
  • Always use a unique reference value for each transaction, duplicate references will be rejected.
  • Start with small test amounts (₦100) to validate your integration before going live.
  • Check your sandbox dashboard to confirm transaction results and inspect any errors.