HamroPay Flutter SDK  

HamroPay Flutter SDK allows you to integrate HamroPay checkout in your Flutter apps with a single method call. It supports showing the checkout either as a full page or a bottom sheet and provides a simple API to configure payment parameters and receive the transaction result.

---

Installation

Add the package to your pubspec.yaml and run flutter pub get.

dependencies:
  hamropay_flutter: ^0.0.1

If you are consuming this from pub.dev, use the published version instead of path.

---

Features

• Easy integration and simple API
• Supports full-page or bottom-sheet checkout
• Pure Dart interface powered by flutter_inappwebview
• Works with product lists and optional phone number

---

Requirements

• Android: minSdkVersion 19+ and AndroidX
• iOS: Xcode 11+, Swift iOS project

This SDK uses flutter_inappwebview. See its platform notes for any additional steps.

---

Quick Start

1. Import the SDK

import 'package:hamropay_flutter/hamropay_flutter.dart';

2. Create a config

final config = HamroPayConfig.dev(
  clientId: 'YOUR_CLIENT_ID',
  clientApiKey: 'YOUR_CLIENT_API_KEY',
  clientSecret: "OUR_CLIENT_SECRET",
  merchantId: 'YOUR_MERCHANT_ID',
  merchantTransactionId: 'UNIQUE_TXN_ID_123', //LESS THAN or EQUAL to 36 characters
  /*
 Amount in Paisa. Should be in Range of Rs.10 to Rs.50000. 
 i.e Rs.10 = 1000,
 Rs.89.92 = 8992
 */
  transactionAmount: 500, // transaction amount must be in long type value & Should be in Range of Rs.10 to Rs.50000.
  products: [
    Product(
      name: 'Sample Item',
      imageUrl: 'https://example.com/item.png',
      description: 'Item description',
      price: 99.99, //Amount in Rs. for render purpose so Rs.99.99 should be 99.99
      quantity: 1,
    ),
  ],
  phoneNumber: '98XXXXXXXX',
);

3. Start payment

final result = await HamroPay.instance.pay(
  context: context,
  hamroPayConfig: config,
);

if (result.data != null) {
  // Handle success/terminal state using result.data
} else if (result.error != null) {
  // Handle failure/cancel state using result.error
}

To show checkout in a bottom sheet:

final result = await HamroPay.instance.pay(
  context: context,
  hamroPayConfig: config,
  displayMode: HamroPayDisplayMode.bottomSheet,
  bottomSheetConfig: BottomSheetConfig(
    initialChildSize: 0.95,
    isDismissible: false,
    enableDrag: false,
  ),
);

---

Screenshots

Here are some screenshots of the Hamro Pay Payment Gateway integrated into a ecommerce Flutter app:

---

API Overview

• HamroPay.instance.pay(...) starts the payment flow and returns Future<HmaroPayPaymentResult>.
• HamroPayConfig.dev(...) and HamroPayConfig.live(...) construct configs for UAT/Production.
• HamroPayButton is a ready-made button widget you can place in your UI.

HamroPayConfig

HamroPayConfig.dev({
  required String clientId,
  required String clientApiKey,
  required int transactionAmount,
  required String merchantId,
  required String merchantTransactionId,
  String serverUrl, // defaults to UAT base URL
  List<Product>? products,
  String? phoneNumber,
  String? successRedirectionUrl,
  String? failedRedirectionUrl,
});

Use .live(...) for production. Supply your own IDs/keys and ensure your backend is configured with the same credentials.

Display modes

• HamroPayDisplayMode.page (default): navigates to a new page.
• HamroPayDisplayMode.bottomSheet: shows the checkout in a modal bottom sheet.

Result type

class HmaroPayPaymentResult {
  final TransactionStatusResponse? data; // present on success/terminal states
  final String? error; // present on failure/cancel
  bool get hasData;
  bool get hasError;
}

---

Platform setup

This SDK uses flutter_inappwebview. Ensure your project meets its platform requirements:

• Android: Minimum Android SDK and WebView support per the plugin docs.
• iOS: Add required WebView permissions if applicable.

Also make sure the asset assets/png/hamro-pay.png is available if you customize the app bar logo in the checkout screen.

---

Notes and Security

• Demo constants in utils/constants/api-constants.dart are placeholders. Replace them with your own secure values and never ship secrets in client apps. Generate signatures on a trusted server when possible.
• Ensure serverUrl points to your backend gateway for creating session IDs and checking transaction status.

---

Example

See the example/ app for a runnable integration example.

---

Run the example app

• Navigate to the example folder: cd example
• Install dependencies: flutter pub get
• Configure your IDs/keys in your example (use HamroPayConfig.dev() for UAT)
• Run: flutter run

---

Dev Testing Information

If you want to test Hamropay payment integration in development environment, you can use the following information:

• clientId: Your Client ID code provided by hamropay.

• clientSecret: Your Client Secret code provided by hamropay.

• clientApiKey: Your Client API KEY code provided by hamropay.

• merchantId: Your MERCHANT ID code provided by hamropay.

• merchantTransactionId: Your MERCHANT TRANSACTION ID code provided by hamropay.

• Test Hamro-pay IDs: You can use any of the following test Hamropay IDs for testing purposes:

  • 9800000008

• Password: 0000

• OTP: 000000

Note: These are Hamropay test credentials and are unrelated to HamroPay production credentials. Do not ship any secrets in client apps.

---

License

This project is available under the terms of the LICENSE file in this repo.

---

Contributions

Contributions are welcome! Please open an issue or submit a pull request.

Contact

Questions or suggestions? Reach out via issues or your preferred channel.