Flutter Payment Plugin — Step‑by‑Step Integration

This guide explains how to add and use flutter_payment_plugin in any Flutter app.

1) Add the Package

• Run: flutter pub add flutter_payment_plugin
• Import: import 'package:flutter_payment_plugin/flutter_payment_plugin.dart';

2) Android Setup

• No additional Android changes are required.

3) iOS Setup

• To make the deep links to open payment apps, add these URL schemes to ios/<YourAppName>/Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
  <!-- Add the schemes you plan to support -->
  <string>upi</string>
  <string>gpay</string>
  <string>phonepe</string>
  <string>paytm</string>
  <!-- etc. -->
</array>

4) Prepare Your Inputs

• url: your payment gateway base domain (e.g., https://your-gateway.example)
• params must include at least: api_key, order_id, salt, hash, mode, amount, name, phone, email, return_url
• Optional fields as required by your gateway: description, currency, country, city, state, address_line_1, address_line_2, zip_code, enable_auto_refund, udf1–udf5

Hashing Logic (Recommended on Backend)

While it is highly recommended to generate the secure hash on your backend, here is the Dart logic for reference. The hash generation requires camelCase keys for sorting, even though the final request uses snake_case.

import 'dart:convert';
import 'package:crypto/crypto.dart'; // Add crypto: ^3.0.0 to pubspec.yaml

String generateHash({
  required String salt,
  required String apiKey,
  required Map<String, String> camelCaseInputs,
}) {
  // 1. Prepare map with REQUIRED camelCase keys
  final Map<String, String> params = {
    "aaaasalt": salt,
    "apiKey": apiKey,
    "mode": camelCaseInputs["mode"] ?? "",
    "amount": camelCaseInputs["amount"] ?? "",
    "name": camelCaseInputs["name"] ?? "",
    "phone": camelCaseInputs["phone"] ?? "",
    "email": camelCaseInputs["email"] ?? "",
    "returnURL": camelCaseInputs["returnURL"] ?? "",
    "description": camelCaseInputs["description"] ?? "",
    "currency": camelCaseInputs["currency"] ?? "",
    "country": camelCaseInputs["country"] ?? "",
    "city": camelCaseInputs["city"] ?? "",
    "state": camelCaseInputs["state"] ?? "",
    "addressLine1": camelCaseInputs["addressLine1"] ?? "",
    "addressLine2": camelCaseInputs["addressLine2"] ?? "",
    "zipCode": camelCaseInputs["zipCode"] ?? "",
    "enable_auto_refund": camelCaseInputs["enable_auto_refund"] ?? "",
    "orderID": camelCaseInputs["orderID"] ?? "",
  };

  // 2. Sort keys alphabetically
  final entries = params.entries.toList()..sort((a, b) => a.key.compareTo(b.key));

  // 3. Join non-empty values with '|'
  final buffer = StringBuffer();
  for (final e in entries) {
    final v = e.value.trim();
    if (v.isNotEmpty) buffer.write('|$v');
  }
  if (buffer.isEmpty) return "";

  // 4. Remove leading '|'
  final toHash = buffer.toString().substring(1); 

  // 5. Generate SHA-512 and convert to Uppercase Hex
  final digest = sha512.convert(utf8.encode(toHash));
  return digest.bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join().toUpperCase();
}

5) Trigger the Payment

Future<void> startPayment() async {
  final params = <String, String>{
    'api_key': 'YOUR_API_KEY',
    'order_id': 'YOUR_ORDER_ID',
    'salt': 'YOUR_SALT',
    'hash': 'YOUR_GENERATED_HASH',
    'mode': 'LIVE',
    'amount': '100',
    'name': 'Buyer Name',
    'phone': '9999999999',
    'email': 'buyer@example.com',
    'return_url': 'https://your.domain/return',
    // optional fields...
  };

  final result = await FlutterPaymentPlugin.openPayment(
    url: 'https://your-gateway.example',
    params: params,
    title: 'Payment',
  );

  if (result.cancelled) {
    // Handle cancellation
  } else if (result.success) {
    // Handle success, check result.data if provided
  } else {
    // Handle failure, inspect result.data
  }
}

6) Integration Tips

• Ensure all required fields are set and trimmed.
• Use a reachable return_url provided by your gateway.
• Prefer generating hash securely on your backend.
• Provide only the base url; the plugin handles the payment endpoint internally.

7) Releasing a new version

When cutting a release, update the version in all three places so clients and CocoaPods see the same version:

1. pubspec.yaml — version: x.y.z
2. ios/flutter_payment_plugin.podspec — s.version = 'x.y.z'
3. lib/flutter_payment_plugin.dart — static const String version = 'x.y.z';

Then run flutter pub publish (and in apps: flutter pub get, then cd ios && pod install or pod update flutter_payment_plugin to refresh the iOS pod).

8) Common Issues

• Wrong base URL: ensure your url points to the correct gateway domain.
• Network errors: check device connectivity and the base url.
• iOS deep links: add URL schemes for the apps your flow targets.