NehilKoshiya/uni_payments

final result = await UniPayments.payWithRazorpay(
  keyId: 'YOUR_RAZORPAY_KEY_ID',
  amount: 25.00,
  businessName: 'Acme Inc',
  customer: UniCustomer(name: 'Ada', email: 'ada@x.com', phone: '9999999999'),
);

switch (result) {
  case PaymentSuccess(:final transactionId): /* verify on backend */
  case PaymentFailure(:final errorCode, :final message): /* show error */
  case PaymentCancelled(): /* user dismissed the sheet */
}

Swap payWithRazorpay for payWithStripe, payWithPaypal, payWithGooglePay, … every gateway still returns the same PaymentResult, while some hosted/native sheets also need a BuildContext.

Why this exists

Thirteen gateway SDKs ship thirteen call shapes, thirteen response objects, thirteen ways the user can cancel. Even when you wrap them, "user closed the sheet" usually disappears into a generic catch.

Uni Payments replaces all of that with a single sealed result type that the Dart compiler forces you to exhaust — every switch you write is checked at compile time, so you can't forget the cancel case again.

Gateways

Every imperative call returns Future<PaymentResult>. Wallet buttons exist because Google + Apple's brand guidelines require their own button design.

Install

dependencies:
  uni_payments: ^0.0.9

flutter pub add uni_payments

import 'package:uni_payments/uni_payments.dart';

Platform requirements

Required extra setup

android {
  defaultConfig {
    minSdk = 28
  }
}

allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url = uri("https://phonepe.mycloudrepo.io/public/repositories/phonepe-intentsdk-android") }
  }
}

maven { url 'https://phonepe.mycloudrepo.io/public/repositories/phonepe-intentsdk-android' }

Core types

UniCustomer

Pass once, reuse everywhere a gateway prefills checkout fields.

const customer = UniCustomer(
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  phone: '9999999999', // optional
);

PaymentResult

sealed class PaymentResult {
  String? gatewayName;       // 'razorpay', 'stripe', 'apple_pay', …
  String? message;
  Map<String, dynamic>? rawResponse;
}

final class PaymentSuccess   extends PaymentResult { String transactionId; }
final class PaymentFailure   extends PaymentResult { String errorCode; String message; }
final class PaymentCancelled extends PaymentResult { }

rawResponse holds the untouched gateway payload — useful for audit logs and webhook reconciliation.

UniPayments.isWalletSupported

Probe before rendering a wallet button — the underlying pay package silently no-ops on unsupported platforms.

final canApplePay = await UniPayments.isWalletSupported(
  WalletProvider.applePay,
  configJson,
);

Per-gateway cookbook

final result = await UniPayments.payWithRazorpay(
  keyId: 'YOUR_RAZORPAY_KEY_ID',
  amount: 25.00,                    // major units (₹25.00)
  businessName: 'Acme Inc',         // merchant header inside the sheet
  customer: customer,
  description: 'Pro subscription',
  themeColor: Colors.indigo,        // Color, not '#RRGGBB'
  currency: 'INR',
  timeout: const Duration(minutes: 5), // optional — see below
);

final result = await UniPayments.payWithStripe(
  publishableKey: 'YOUR_STRIPE_PUBLISHABLE_KEY',
  clientSecret: 'YOUR_PAYMENT_INTENT_CLIENT_SECRET',     // from your server
  merchantDisplayName: 'Acme Inc',
  merchantCountryCode: 'US',

  // Optional — Apple Pay / Google Pay inside the PaymentSheet
  applePayMerchantId: 'merchant.com.acme.app',
  googlePayTestEnv: true,

  // Optional — saved cards (ephemeral key from your server)
  customerId: 'cus_xxx',
  customerEphemeralKeySecret: 'ek_test_xxx',
);

final result = await UniPayments.payWithPaypal(
  context: context,
  tokenizationKey: 'YOUR_BRAINTREE_TOKENIZATION_KEY',
  amount: 25.00,
  customer: customer,
  currency: 'USD',
  countryCode: 'US',
  applePayMerchantId: 'merchant.com.acme', // optional
);

final result = await UniPayments.payWithPaystack(
  context: context,
  secretKey: 'YOUR_PAYSTACK_SECRET_KEY',
  amount: 25.00,
  customer: customer,
  reference: 'ref_${DateTime.now().millisecondsSinceEpoch}',
  callbackUrl: 'https://acme.dev/paystack/callback',
  currency: UniPaystackCurrency.usd,
);

final result = await UniPayments.payWithFlutterwave(
  context: context,
  publicKey: 'YOUR_FLUTTERWAVE_PUBLIC_KEY',
  currency: 'NGN',
  amount: 25.00,
  customer: customer,
  txRef: 'tx_${DateTime.now().millisecondsSinceEpoch}',
  redirectUrl: 'https://acme.dev/flutterwave/return',
  testMode: true,
);

// txnToken is issued by your backend via Paytm's initiateTransaction API.
final result = await UniPayments.payWithPaytm(
  merchantId: 'YOUR_MERCHANT_ID',
  orderId: 'order_${DateTime.now().millisecondsSinceEpoch}',
  txnToken: 'YOUR_TXN_TOKEN',
  amount: 25.00,
  useStagingEnvironment: true,
);

// orderId + paymentSessionId come from your backend's call to the
// Cashfree Orders API.
final result = await UniPayments.payWithCashfree(
  orderId: 'order_${DateTime.now().millisecondsSinceEpoch}',
  paymentSessionId: 'session_xxx',
  useStagingEnvironment: true,
  timeout: const Duration(minutes: 5), // optional, see below
);

// requestBody is a base64-encoded JSON request your backend signs.
final result = await UniPayments.payWithPhonepe(
  merchantId: 'YOUR_MERCHANT_ID',
  flowId: 'flow_${DateTime.now().millisecondsSinceEpoch}',
  requestBody: '<base64-encoded JSON from your backend>',
  appSchema: 'unipaymentsdemo', // iOS URL scheme; '' on Android
  useStagingEnvironment: true,
);

// Backend hands you a hash for every step PayU asks you to sign — see
// https://devguide.payu.in/flutter-sdk-integration/. Never compute this
// with the salt on-device.
Future<Map<dynamic, dynamic>> generateHash(Map<dynamic, dynamic> request) async {
  final response = await yourBackend.post('/payu/hash', body: request);
  return response.data; // e.g. { hashName: 'computedHashValue' }
}

final result = await UniPayments.payWithPayu(
  merchantKey: 'YOUR_PAYU_MERCHANT_KEY',
  amount: 25.00,
  productInfo: 'Pro subscription',
  customer: customer,
  transactionId: 'txn_${DateTime.now().millisecondsSinceEpoch}',
  successUrl: 'https://acme.dev/payu/success',
  failureUrl: 'https://acme.dev/payu/failure',
  generateHash: generateHash,
  useStagingEnvironment: true,
);

final result = await UniPayments.payWithSquare(
  applicationId: 'YOUR_SQUARE_APPLICATION_ID', // sandbox-sq0idb-... or sq0idp-...
);

final result = await UniPayments.payWithAirwallex(
  clientSecret: 'YOUR_PAYMENT_INTENT_CLIENT_SECRET', // from your server
  paymentIntentId: 'YOUR_PAYMENT_INTENT_ID',
  amount: 25.00,
  currency: 'USD',
  countryCode: 'US',
  useStagingEnvironment: true,
);

// Imperative
final result = await UniPayments.payWithGooglePay(
  paymentConfigurationJson: configJson,
  lineItemLabel: 'Total',
  amount: 25.00,
);

// Native button
UniPayments.googlePayButton(
  paymentConfigurationJson: configJson,
  lineItemLabel: 'Total',
  amount: 25.00,
  buttonType: UniGooglePayButtonType.pay,
  onResult: (PaymentResult result) { /* … */ },
);

final result = await UniPayments.payWithApplePay(
  paymentConfigurationJson: configJson,
  lineItemLabel: 'Total',
  amount: 25.00,
);

UniPayments.applePayButton(
  paymentConfigurationJson: configJson,
  lineItemLabel: 'Total',
  amount: 25.00,
  type: UniApplePayButtonType.buy,
  onResult: (PaymentResult result) { /* … */ },
);

Demo app

The repo ships a fully-styled demo with all thirteen gateways wired up — animated gradient background, glass-morphism tiles, error toasts, haptic feedback on each outcome.

git clone https://github.com/NehilKoshiya/uni_payments
cd uni_payments/example
flutter pub get
flutter run

Security notes

Secrets

• Never ship secret/private keys in your app binary. secretKey (Paystack), the PayU merchant salt, and Stripe/Airwallex clientSecrets must be generated or held on your server — a decompiled APK/IPA hands over anything embedded in it.
• PayU signs every checkout step with an HMAC computed from your salt. This package never computes that hash — payWithPayu's generateHash callback exists specifically so the salt stays server-side; don't be tempted to inline the hash logic on-device "just for testing."

Verification

• A client-side result is a claim, not a fact — the device can lie, crash mid-flow, or lose network after the charge actually succeeded. Always reconcile server-side before fulfilling an order:
  • PaymentSuccess — re-check with the gateway (fetch the payment/order by id, or wait for its webhook) before shipping anything.
  • PaymentFailure / PaymentCancelled — don't assume no money moved. Bank debits and UPI/wallet redirects can complete after the client already gave up; several gateways in this package surface that explicitly as a specific errorCode (e.g. external_wallet_pending from Razorpay, payment_in_progress from Airwallex, cashfree_already_in_progress) precisely so you don't silently treat "ambiguous" as "definitely unpaid."
• Where the gateway signs its response (Razorpay's orderId/signature in rawResponse, Paytm's checksum, PayU's hash), verify that signature server-side too — rawResponse carries the untouched payload specifically so your backend has something to check against, not just log.

Reliability

• Use a genuinely unique reference / transactionRef / orderId / transactionId per attempt (not reused across retries) — every gateway that takes one uses it to detect duplicate charges on their end.
• payWithRazorpay and payWithCashfree accept an optional timeout — without one, a native SDK that never calls back (killed app, OEM quirk) leaves the Future pending forever with no way for your UI to recover.

Dependencies

• Every native SDK this package wraps is vetted for maintenance status before being added — see the CHANGELOG for two rejected candidates (a discontinued package, and one with a confirmed native-bridge bug) and the reasoning behind each. If you're auditing your own dependency tree, that's a good place to see the bar this package holds itself to.
• Keep flutter_stripe and the other native SDKs current — dart pub outdated should show no available upgrades left on the table; payment SDKs receive security-relevant patches (fraud signals, TLS/crypto updates) more often than most packages.

Contributing

• Bug or feature request — open an issue.
• Found this useful? A ⭐ on GitHub goes a long way.

Local setup

git clone https://github.com/NehilKoshiya/uni_payments
cd uni_payments
flutter pub get
flutter test
cd example && flutter pub get

Before sending a PR

• flutter analyze must be clean. This package runs with strict-casts, strict-inference and strict-raw-types on top of flutter_lints (see analysis_options.yaml) — code that's merely "lint-clean" elsewhere may still fail here.
• flutter test must pass.
• Update CHANGELOG.md under a new version heading describing what changed and why — not just what.
• If your PR touches the example app, run it once (cd example && flutter run) and exercise the affected gateway's tile before opening the PR — analysis and tests don't catch a broken demo wiring.

Adding a new gateway

Every gateway in this package follows the same shape, so a new one is mostly mechanical:

1. lib/src/gateways/<name>_gateway.dart — a stateless <Name>Gateway class with a pay(...) method that awaits/wraps the upstream SDK and maps its outcome onto PaymentSuccess / PaymentFailure / PaymentCancelled. Give it a const _gatewayName = '<name>'; matching the public method name, and stash the untouched upstream response in rawResponse wherever you can.
2. lib/src/uni_payments.dart — add a payWithXxx(...) static method that validates required fields via _validate(...) and delegates to the new gateway. Document any upstream quirks in the doc comment (see payWithCashfree for an example of calling out an upstream concurrency limitation).
3. pubspec.yaml — add the dependency, and check its environment: constraint before pinning — don't silently raise this package's Flutter/Dart floor for an optional gateway (see the square_in_app_payments comment for the pattern).
4. example/ — add a tile (lib/data/gateway.dart), a demo method (lib/services/payment_demos.dart), wire it into the dispatch map (lib/ui/home_screen.dart), and add a brand color/letter fallback (lib/ui/brand_icon.dart) if Simple Icons doesn't have the logo.
5. README.md — add a row to the Gateways table and a cookbook entry under Per-gateway cookbook.
6. CHANGELOG.md — new gateways get their own entry under "New gateways."

Before proposing a gateway, do the same vetting this package already applies: check pub.dev for maintenance status (points, likes, last published date, and whether it's marked discontinued), and skim the native bridge source for obvious gaps (does every outcome — including cancellation — actually reach Dart?). Two candidates were rejected for exactly these reasons; see the CHANGELOG.