flutter_fincra_checkout 0.1.0

Production-ready Flutter Checkout SDK for Fincra with native in-app WebView, smart callback interception, and strongly typed payment results.

Flutter Fincra Checkout

A production-ready Flutter package that provides a clean, secure, and highly customizable integration for Fincra Checkout payments using an in-app WebView.

---

🔒 Important Note on Security

DO NOT store your Fincra secret keys inside your Flutter application. This SDK is designed to handle only the mobile frontend checkout experience. The actual payment session must be created securely from your backend server.

✨ Features

• 📱 Two Checkout Modes: Native WebView or Inline JavaScript Checkout.
• 🔗 Automatic detection of payment completion URL changes.
• 🎨 Highly customizable UI (AppBar, colors, loaders, close icons).
• 🛡️ Built-in dialogs to prevent accidental user cancellation.
• ⚡ Dual integration APIs (Supports both async/await and traditional Callbacks).
• 🐛 Built-in error handling for seamless debugging.

📦 Installation

Add the dependency to your pubspec.yaml:

dependencies:
  flutter_fincra_checkout: ^1.0.0

🛠️ Setup

Android

Ensure your minSdkVersion in android/app/build.gradle is at least 19 (WebView requirements). Also, add internet permissions in your AndroidManifest.xml if not already present:

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

iOS

No additional configuration is required for recent versions of Flutter.

(Note: If you are using an extremely old Flutter version < 1.22, you may need to opt-in to embedded views in your Info.plist).

---

🚀 Usage

The SDK now supports two separate checkout modes: WebView Checkout and Inline Checkout.

Checkout Modes

Feature	WebView	Inline
Custom reference	Yes	Yes
Backend required	Recommended	Depends
Secret key in app	No	No
Native experience	Yes	Yes

---

1. WebView Checkout (Recommended)

This is the standard and recommended production flow where the payment session is created on your backend using your Secret Key.

Step 1: Create a Payment Session (Backend)

Your backend should securely communicate with the Fincra API to initiate a checkout session and return the checkoutUrl.

Step 2: Open WebView Checkout (Flutter)

import 'package:flutter/material.dart';
import 'package:flutter_fincra_checkout/flutter_fincra_checkout.dart';

Future<void> _startWebViewPayment(BuildContext context) async {
  final result = await FincraCheckout.openWebView(
    context,
    config: WebViewCheckoutConfig(
      checkoutUrl: "https://checkout.fincra.com/pay/...",
      redirectUrl: "https://your-backend.com/webhook", // Optional
      appBarTitle: "Complete Payment",
      appBarBackgroundColor: Colors.white,
      showCancelConfirmationDialog: true,
    ),
  );
  
  if (!context.mounted) return;
  _handleResult(result);
}

---

2. Inline JavaScript Checkout

The inline checkout flow allows you to trigger a payment directly from the app using your Public Key. Do NOT use your Secret Key here.

Open Inline Checkout (Flutter)

Future<void> _startInlinePayment(BuildContext context) async {
  final result = await FincraCheckout.openInline(
    context,
    config: const InlineCheckoutConfig(
      publicKey: "pk_...", // ONLY use your Fincra PUBLIC key
      amount: 1500,
      currency: FincraCurrency.ngn,
      customerEmail: "[e-mail]",
      customerName: "John Doe",
      customerPhoneNumber: "08012345678",
      reference: "CUSTOM-REF-123", // Optional
      paymentMethods: ["bank_transfer", "card", "payattitude"], // Optional
    ),
  );
  
  if (!context.mounted) return;
  _handleResult(result);
}

---

Result Handling

Both checkout modes return the same FincraCheckoutResult type, allowing you to use a single result handler:

void _handleResult(FincraCheckoutResult result) {
  switch (result) {
    case FincraCheckoutSuccess():
      print("Success! Reference: ${result.response.reference}");
      break;
    case FincraCheckoutError():
      print("Failed: ${result.error.message}");
      break;
    case FincraCheckoutCancelled():
      print("User cancelled");
      break;
  }
}

Advanced: Custom Layout

If you want full control over the layout (e.g., embedding the checkout in a Bottom Sheet or a specific container instead of a full screen), you can use the raw widgets directly.

For WebView:

CheckoutWebView(
  checkoutUrl: "https://checkout.fincra.com/...",
  redirectUrl: "https://your-backend.com/webhook",
  appBarTitle: "Secure Payment",
)

For Inline:

InlineCheckout(
  config: const InlineCheckoutConfig(
    publicKey: "pk_...",
    amount: 1500,
    currency: FincraCurrency.ngn,
    customerEmail: "[e-mail]",
    customerName: "John Doe",
    customerPhoneNumber: "08012345678",
    paymentMethods: ["card"],
    feeBearer: FeeBearer.customer,
  ),
)

Configuration Parameters

The configurations for both modes accept various parameters to help you tailor the checkout experience.

WebViewCheckoutConfig

Parameter	Type	Description
checkoutUrl	String	(Required) The generated payment URL from your backend.
redirectUrl	String?	The callback URL your backend sent to Fincra. Used to securely intercept the completion page before Fincra redirects back.
appBarTitle	String?	Sets a custom title for the WebView's AppBar.
appBarBackgroundColor	Color?	Customizes the background color of the AppBar to match your app's theme.
closeIcon	Widget?	Replaces the default exit button (e.g., Icon(Icons.close)).
loadingWidget	Widget?	A custom loading indicator displayed while the payment page is initially loading.
showCancelConfirmationDialog	bool	Set to true to show a confirmation dialog when the user tries to exit the checkout prematurely. Defaults to false.

InlineCheckoutConfig

Parameter	Type	Description
publicKey	String	(Required) Your Fincra public key.
amount	num	(Required) The transaction amount.
currency	FincraCurrency	(Required) The currency code enum (e.g., FincraCurrency.ngn).
customerEmail	String	(Required) The customer's email.
customerName	String	(Required) The customer's full name.
customerPhoneNumber	String	(Required) The customer's phone number.
feeBearer	FeeBearer	(Required) Determines who pays the fees (FeeBearer.business or FeeBearer.customer).
reference	String?	Optional custom transaction reference.
paymentMethods	List<String>?	Optional list of allowed payment methods (e.g., ["card", "bank_transfer"]).

Note: Both FincraCheckout.openWebView and FincraCheckout.openInline also accept optional onSuccess, onFailed, and onCancelled callbacks if you prefer that over async/await.

---

📚 Models

FincraPaymentResponse

Property	Type	Description
reference	String	The unique transaction reference.
transactionId	String	Fincra's internal transaction ID.
status	String	The status of the transaction (e.g., 'success').
message	String?	Optional message from Fincra.
rawResponse	Map	The raw parameters extracted from the completion URL.

FincraPaymentError

Property	Type	Description
code	String	The error code or status.
message	String	A description of the error.

💡 Example

Check out the example/ directory for a complete working application demonstrating the payment flow.