bank78_checkout 0.0.3 copy "bank78_checkout: ^0.0.3" to clipboard
bank78_checkout: ^0.0.3 copied to clipboard

Published 4 days ago • verified publisherbank78.co
SDKFlutter
PlatformAndroidiOSLinuxmacOSWindows
→

Metadata

Bank78 MFB's Flutter package.

More...

Bank78 Checkout Flutter SDK #

pub package Flutter Dart License

The official Bank78 Checkout SDK for Flutter. Seamlessly integrate native, high-performance, secure checkout experiences directly into your Flutter iOS and Android applications.

Unlike hosted web checkout solutions, this SDK renders native input forms and payment widgets (Card, Bank Transfer, and Pay with Bank78) within your application while keeping sensitive card details encrypted and compliant with Bank78 security standards.

Table of Contents #

Features #

  • 💳 Native Card Checkout: Clean card input fields with automatic card brand detection (Visa, Mastercard, Verve), expiry/CVV validation, and PIN support.
  • 🏦 Dynamic Virtual Account Bank Transfers: Instant virtual account generation with one-tap copy functionality and status polling.
  • ⚡ Pay with Bank78: Direct customer authentication and wallet/account payment processing.
  • 🔒 End-to-End Payload Encryption: Built-in RSA-OAEP + AES-256-GCM envelope encryption protecting card details and sensitive request payloads.
  • 🎨 Dark / Light Theme Styling: Modern UI modal designed to blend seamlessly into your Flutter application design.
  • 🌐 Multi-Environment Support: Seamless switching between development (Sandbox) and production environments.

Roles & Architectural Boundaries #

Actor Responsible For Must NOT Contain
Merchant Backend Creates order/session (/api/merchant/*); verifies final order status; handles webhooks Exposed client sessions
Native Mobile SDK Client session rendering, card & payload encryption, calling /api/checkout/sessions/* Merchant secret key or master admin bearer token
Bank78 Customer App / Identity Customer sign-in & Pay with Bank78 authorization Merchant API keys

End-to-End Payment Flow #

sequenceDiagram
    autonumber
    actor Customer
    participant App as Mobile App (Flutter)
    participant Backend as Merchant Backend
    participant SDK as Bank78 Checkout SDK
    participant API as Bank78 Checkout API

    Customer->>App: Initiates Checkout
    App->>Backend: Request checkout session creation
    Backend->>API: POST /api/merchant/orders/checkout
    API-->>Backend: Returns checkoutSessionReference & orderReference
    Backend-->>App: Returns checkoutSessionReference
    App->>SDK: Bank78Checkout.init(config)
    SDK->>API: GET /api/checkout/sessions/security
    API-->>SDK: Public Encryption Key & Security Policy
    SDK->>API: GET /api/checkout/sessions/{sessionReference}
    API-->>SDK: Session details & paymentMethods[]
    SDK-->>Customer: Renders native checkout dialog
    Customer->>SDK: Selects method & enters payment details
    SDK->>API: Encrypted Submit (Card / Bank Transfer / Pay with Bank78)
    API-->>SDK: Success / Pending status update
    SDK-->>App: Dialog completes / status updated
    App->>Backend: Verify order completion
    Backend->>API: GET /api/merchant/orders/{orderReference}/status
    API-->>Backend: Final order status (SUCCEEDED)
    Backend-->>App: Order fulfilled

Installation #

Add bank78_checkout to your Flutter project's pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  bank78_checkout: ^0.0.1

Or run the following command in your terminal:

flutter pub add bank78_checkout

Getting Started #

1. Backend Creates Order & Session #

Before calling the SDK, your backend server must create a checkout session using Bank78's server-to-server merchant API:

POST /api/merchant/orders/checkout
Authorization: Bearer {merchant_bearer_token}
Content-Type: application/json

{
  "amount": 15000,
  "currency": "NGN",
  "description": "Payment for Order #1024"
}

The response returns a checkoutSessionReference (e.g., chk_123456789). Pass this reference to your Flutter mobile app.

2. Initialize Native Checkout SDK #

Trigger the Bank78 native checkout modal in your Flutter app by calling Bank78Checkout.init():

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

void startCheckout(BuildContext context, String checkoutReference) {
  Bank78Checkout.init(
    Bank78CheckoutConfig(
      context: context,
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
      apiKey: 'YOUR_API_KEY',
      reference: checkoutReference, // e.g. "chk_123456789"
      returnUrl: 'https://your-domain.com/checkout/return', // Optional return URL
      cancelUrl: 'https://your-domain.com/checkout/cancel', // Optional cancel URL
      environment: Bank78CheckoutEnv.development, // Use .production for live apps
    ),
  );
}

Configuration Reference #

Bank78CheckoutConfig #

The Bank78CheckoutConfig class configures the behavior and environment of the SDK.

Parameter Type Required Default Description
context BuildContext Yes — The current build context used to display the modal overlay dialog.
clientId String Yes — Merchant Client ID provided in your Bank78 Merchant Dashboard.
clientSecret String Yes — Merchant Client Secret for authentication.
apiKey String Yes — Merchant API Key (x-api-key).
reference String Yes — The checkoutSessionReference generated by your backend for this payment.
returnUrl String No — Callback URL or deep link redirected to after successful payment.
cancelUrl String No — Callback URL or deep link redirected to if payment is cancelled or abandoned.
environment Bank78CheckoutEnv No development Targeted Bank78 server environment (development or production).
grantType String No 'client_credentials' Authentication grant type.

Bank78CheckoutEnv #

Environment Enum Base URL Usage
Bank78CheckoutEnv.development https://sandbox.bank78.co Testing & Sandbox integration
Bank78CheckoutEnv.production https://api.bank78.co Live production transactions

Supported Payment Methods #

Card Payments #

  • Accepts Visa, Mastercard, and Verve cards.
  • Handles card numbers, expiration dates, CVVs, and cardholder names.
  • Supports card PIN entry dynamically when required by the issuing gateway (gateway.requiresCardPin == true).
  • Supports 3-D Secure (3DS) authentication challenges.

Bank Transfers #

  • Dynamically generates temporary virtual bank account details (Bank Name, Account Number, Account Name, Expiry).
  • Displays countdown timer for account validity.
  • Provides copy-to-clipboard buttons for seamless transfer from banking apps.
  • Automatic transfer status polling and manual confirmation triggering.

Pay with Bank78 #

  • Enables direct checkout for Bank78 account holders.
  • Handoff token exchange and secure customer PIN verification.

Security & Encryption Architecture #

The bank78_checkout SDK prioritizes customer data security. Raw card details and sensitive request payloads are encrypted on the mobile device before transmission:

  1. Security Configuration Retrieval: Upon initialization, the SDK fetches client security configurations (GET /api/checkout/sessions/security).
  2. Payload Protection:
    • Payload is serialized as UTF-8.
    • Generates a fresh 32-byte AES key and 12-byte IV for every encrypted request.
    • Encrypts payload with AES-256-GCM.
    • Encrypts the AES key with Bank78's RSA public key (RSA-OAEP-SHA256).
    • Applies replay protection using timestamps and unique nonces.

Session Lifecycle & Statuses #

The session status reflects the real-time state of the payment:

Session Status Description Action Required
PENDING Session created, awaiting payment selection or processing. User interacts with SDK UI.
PROCESSING Payment attempt submitted; authorization or reconciliation in progress. SDK polls for completion.
SUCCEEDED Payment successfully completed. SDK displays success feedback. Merchant backend verifies and fulfills order.
FAILED Payment failed due to insufficient funds, decline, or validation error. SDK prompts retry.
CANCELLED Session cancelled by user or expired. SDK closes modal.

Note: Your backend must independently verify the order status via GET /api/merchant/orders/{orderReference}/status prior to fulfilling goods or services.

Complete Integration Example #

Here is a full working example demonstrating how to integrate bank78_checkout inside a Flutter screen:

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Bank78 Checkout Demo',
      theme: ThemeData.dark(),
      home: const HomeScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  void _launchCheckout(BuildContext context) {
    // 1. In a production app, obtain 'reference' from your backend endpoint
    const sampleCheckoutReference = 'chk_demo_987654321';

    // 2. Initialize Bank78 Checkout SDK
    Bank78Checkout.init(
      Bank78CheckoutConfig(
        context: context,
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET',
        apiKey: 'YOUR_API_KEY',
        reference: sampleCheckoutReference,
        returnUrl: 'https://your-domain.com/checkout/return',
        cancelUrl: 'https://your-domain.com/checkout/cancel',
        environment: Bank78CheckoutEnv.development,
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Bank78 Checkout'),
      ),
      body: Center(
        child: ElevatedButton(
          style: ElevatedButton.styleFrom(
            backgroundColor: Colors.greenAccent,
            foregroundColor: Colors.black,
            padding: const EdgeInsets.symmetric(horizontal: 32, vertical: 16),
          ),
          onPressed: () => _launchCheckout(context),
          child: const Text(
            'Pay with Bank78',
            style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
          ),
        ),
      ),
    );
  }
}

Troubleshooting #

Exception: Bank78Checkout is not initialized. Call init() first. #

This error occurs if Bank78Checkout.instance is accessed prior to invoking Bank78Checkout.init(config). Always ensure init() is called with a valid BuildContext and configuration.

Payment Session Errors #

  • Invalid Session Reference: Ensure your backend creates a fresh checkout session and passes the returned checkoutSessionReference.
  • Encryption Errors: Verify your system clock is accurate, as timestamp tolerance for payload protection is within 5 minutes.

License & Support #

Distributed under the MIT License.

For technical support, integration guidance, or bug reports:

← Metadata

0
likes
150
points
161
downloads

Documentation

API reference

Publisher

verified publisherbank78.co

Weekly Downloads

Metadata

Bank78 MFB's Flutter package.

Homepage

License

MIT (license)

Dependencies

asn1lib, cryptography, dio, equatable, flutter, intl, pointycastle, url_launcher, uuid

More

Packages that depend on bank78_checkout

Back