🏦 FundlyPay

A Flutter library by Fundly Pay for seamless and standardized payment integration.
It enables effortless management of invoice-based and direct payment lifecycles while maintaining a clear separation between system transaction statuses and manual distributor settlements.

This ensures transparent payment tracking, reconciliation, and settlement across multiple payment methods such as Cash, Cheque, Static QR, Dynamic QR, Payment Link, and Fundly Pay.

🚀 Features

✅ Seamless integration for Fundly Pay transactions
✅ Supports both Invoice Collect and Direct Collect payment flows
✅ Easy environment configuration (Sandbox / Production)
✅ Event-driven architecture for handling HOME and CLOSE actions
✅ Secure authentication via credential object (API Key or Username/Password)
✅ Standardized and extensible payment object structure

⚙️ Getting Started

1️⃣ Installation

Add the dependency to your pubspec.yaml:

dependencies:
  fundlypay: ^0.0.5

Then run:

flutter pub get

2️⃣ Import

import 'package:fundlypay/fundlypay.dart';

3️⃣ iOS Configuration (Required)

For UPI payment app integration and media uploads (camera/gallery) on iOS, add the following to your ios/Runner/Info.plist:

<!-- UPI payment app schemes -->
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>phonepe</string>
    <string>paytmmp</string>
    <string>gpay</string>
    <string>upi</string>
    <string>tez</string>
    <string>bhim</string>
    <string>cred</string>
    <string>mobikwik</string>
</array>

<!-- Permissions descriptions for document uploads -->
<key>NSCameraUsageDescription</key>
<string>We need access to the camera to capture invoice and document photos.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to the photo library to upload invoice and document files.</string>

This allows your app to detect/launch payment apps for UPI transactions and handle camera/photo uploads.

4️⃣ Android Configuration (Required)

For Android 11 (API Level 30) and above, package visibility queries must be declared in your android/app/src/main/AndroidManifest.xml. Add the <queries> element inside the <manifest> tag to allow the plugin to detect and launch external UPI payment apps:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <queries>
        <!-- For launching external UPI payment apps -->
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="upi" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="phonepe" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="paytmmp" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="gpay" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="tez" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="bhim" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="cred" />
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="mobikwik" />
        </intent>
    </queries>
</manifest>

🧠 Inputs to Library

1. Credentials

Option 1 — Username/Password

"credential": {
  "username": "demo_user",
  "password": "dummy_password_123",
  "source": "SOURCE_APP"
}

Option 2 — API Key

"credential": {
  "apiKey": "dummy_api_key_123",
  "source": "SOURCE_APP"
}

2. Payment Details

💰 Invoice Collect

"paymentDetails": {
  "distributorId": "DISTRIBUTOR1234",
  "chemistId": "CHEMIST1234",
  "paymentType": "INVOICE_COLLECT",
  "payableAmount": 200.0,
  "invoice": [
    {
      "invoiceNumber": "INV1001",
      "paidAmount": 500.0,
      "invoiceYear": "2025"  // Optional: Invoice year in YYYY format
    },
    {
      "invoiceNumber": "INV1002",
      "paidAmount": 500.0,
      "invoiceYear": "2025"  // Optional
    }
  ]
}

Invoice Object Parameters:

  • invoiceNumber (required): Invoice identifier
  • paidAmount (required): Amount paid for this invoice
  • invoiceYear (optional): Invoice year in YYYY format

💳 Direct Collect

"paymentDetails": {
  "distributorId": "DISTRIBUTOR1234",
  "chemistId": "CHEMIST1234",
  "paymentType": "DIRECT_COLLECT",
  "payableAmount": 200.0,
  "invoices": [
    {
      "invoiceId": "INV101",
      "invoice": [
        {
          "page": "1",
          "url": "https://example.com/invoice_page1.jpg"
        },
        {
          "page": "2",
          "url": "https://example.com/invoice_page2.jpg"
        }
      ]
    },
    {
      "invoiceId": "INV102",
      "invoice": [
        {
          "page": "1",
          "url": "https://example.com/invoice_page1.jpg"
        }
      ]
    }
  ]
}

3. Event Data (Optional)

You can optionally pass custom event tracking or device identification data under the eventData key.

"eventData": {
  "os": "android",            // Optional: Will be auto-detected at runtime if not provided (android/ios)
  "device_type": "mobile",    // Optional: 'mobile' or 'tablet', auto-detected at runtime if not provided
  "custom_tracker_id": "xyz"  // Optional: Any other custom key-value pairs for analytics
}

At runtime, the library automatically enriches this object with the running SDK version (e.g. sdk_version: "0.0.5").

🧩 Enums

enum FundlyPayEvent {
  HOME,
  CLOSE,
}

enum PaymentType {
  DIRECT_COLLECT,
  INVOICE_COLLECT,
}

enum FundlyPayEnvironment {
  PRODUCTION,
  SANDBOX,
}

🧱 Initialization Example

final fundlyPayObject = {
  "credential": credential,
  "paymentDetails": paymentDetails,
};

FundlyPayService(
  fundlyPayObject: fundlyPayObject,
  environment: FundlyPayEnvironment.PRODUCTION,
  onEvent: (event, data) {
    debugPrint("FundlyPayService Event: $event -> $data");

    if (event == FundlyPayEvent.HOME) {
      // Example: Navigator.of(context).popUntil((route) => route.isFirst);
    } else if (event == FundlyPayEvent.CLOSE) {
      // Example: if (Navigator.of(context).canPop()) Navigator.of(context).pop();
    }
  },
);

🧾 Example: Combined Object

final fundlyPayObject = {
  "credential": {
    "username": "demo_user",
    "password": "dummy_password_123",
    "source": "SOURCE_APP",
  },
  "paymentDetails": {
    "distributorId": "D00000000XX",
    "chemistId": "R00000000YY",
    "paymentType": "INVOICE_COLLECT",
    "payableAmount": 1000.0,
    "invoice": [
      {
        "invoiceNumber": "INV1001",
        "paidAmount": 600.0,
        "invoiceYear": "2025"  // Optional parameter
      },
      {
        "invoiceNumber": "INV1002",
        "paidAmount": 400.0,
        "invoiceYear": "2025"  // Optional parameter
      }
    ]
  },
  "eventData": {
    "os": "ios",
    "device_type": "mobile",
    "custom_tracker_id": "analytics_tracker_xyz"
  }
};

🧭 Objective

The Fundly Pay Flutter Library standardizes the payment lifecycle for invoice and direct collections, ensuring consistent handling of:

  • Transaction creation and tracking
  • System vs. manual settlement status separation
  • Unified reconciliation across multiple payment methods

🧩 Supporting Libraries

The FundlyPay Flutter Library is built using the following supporting packages:

Library Purpose
flutter_inappwebview Embeds and manages Fundly Pay's web-based payment flows securely inside Flutter apps.
file_picker Enables users to select and upload invoice or proof-of-payment files.
image_picker Captures or selects images for document uploads or invoice attachments.
flutter_image_compress Optimizes and compresses images before upload to reduce file size and improve performance.
path_provider Manages local directories for caching and file storage.
permission_handler Handles runtime permissions for file, storage, and media access.
share_plus Allows sharing of receipts, payment links, and transaction data.
http Facilitates secure REST API communication with Fundly Pay backend services.
url_launcher Enables launching external payment apps (PhonePe, Paytm, GPay, etc.) for UPI transactions.

🪪 License

Copyright © 2025 Ardour Analytics Private Limited.
All rights reserved.

This software and its source code are the property of Ardour Analytics Private Limited.
Unauthorized copying, distribution, modification, or use of this software, in whole or in part,
is strictly prohibited without prior written permission from Ardour Analytics Private Limited.

This project is proprietary and maintained by Ardour Analytics Private Limited.

💬 Support

For integration or technical assistance:
📧 connect@fundly.ai
🌐 www.fundly.ai

Libraries

fundlypay