micropaysdk 0.1.0

Official Micropay SDK for Flutter - Accept M-Pesa payments in your mobile app

Micropay Flutter SDK

Official Flutter SDK for accepting M-Pesa payments in your mobile app.

Features

• Quick Integration - Drop-in UI components for payment flows
• Native Feel - Platform-adaptive widgets that match iOS and Android
• Secure - PCI-compliant, credentials never touch client code
• Multi-Country - Supports Kenya, Tanzania, Uganda, Rwanda, Malawi
• Customizable - Theming support for brand consistency

Installation

Add micropaysdk to your pubspec.yaml:

dependencies:
  micropaysdk: ^0.1.0

Then run:

flutter pub get

Quick Start

1. Initialize the Client

import 'package:micropaysdk/micropaysdk.dart';

final micropay = Micropay(
  publicKey: 'pk_test_your_public_key',
  debug: true,
);

2. Show the Payment Sheet

final result = await PaymentSheet.show(
  context: context,
  micropay: micropay,
  amount: 50000, // KES 500.00 (amounts in cents)
  currency: 'KES',
  description: 'Premium Subscription',
  onStatusChange: (status) {
    print('Payment status: $status');
  },
);

if (result != null && result.isSucceeded) {
  print('Receipt: ${result.providerReference}');
}

Widgets

MicropayButton

A styled button for initiating payments:

MicropayButton(
  onPressed: () => initiatePayment(),
  amount: 50000,
  currency: 'KES',
  size: MicropayButtonSize.large,
  style: MicropayButtonStyle.primary,
)

Prop	Type	Description
onPressed	VoidCallback?	Callback when button is pressed
amount	int?	Amount in smallest currency unit
currency	String	Currency code (default: 'KES')
label	String?	Custom button label
isLoading	bool	Show loading indicator
isDisabled	bool	Disable the button

MpesaPhoneField

Phone number input with country selector:

MpesaPhoneField(
  controller: phoneController,
  initialCountry: MpesaCountry.kenya,
  labelText: 'M-Pesa Phone Number',
  onChanged: (fullNumber) {
    print('Full number: $fullNumber');
  },
)

Supported Countries:

Country	Dial Code
Kenya	+254
Tanzania	+255
Uganda	+256
Rwanda	+250
Malawi	+265

PaymentSheet

Full-screen payment flow:

final result = await PaymentSheet.show(
  context: context,
  micropay: micropay,
  amount: 50000,
  currency: 'KES',
  description: 'Order #12345',
  metadata: {'orderId': '12345'},
);

API Reference

Micropay Client

final micropay = Micropay(
  publicKey: 'pk_test_...',
  timeout: Duration(seconds: 30),
  debug: false,
);

createPaymentIntent

final intent = await micropay.createPaymentIntent(
  amount: 50000,
  phoneNumber: '254712345678',
  currency: 'KES',
  description: 'Premium upgrade',
  idempotencyKey: 'unique-request-id',
);

confirmPaymentIntent

final confirmed = await micropay.confirmPaymentIntent(
  intent.id,
  intent.clientSecret!,
);

pollPaymentStatus

final result = await micropay.pollPaymentStatus(
  'pi_xxx',
  pollInterval: Duration(seconds: 2),
  maxAttempts: 60,
  onStatusChange: (status) => print('Status: $status'),
);

PaymentIntentStatus

Status	Description
requiresConfirmation	Awaiting confirmation
processing	STK Push sent, awaiting user
succeeded	Payment completed
failed	Payment failed
cancelled	Payment cancelled

Error Handling

try {
  final intent = await micropay.createPaymentIntent(...);
} on MicropayError catch (e) {
  print('Error code: ${e.code}');
  print('Message: ${e.message}');
  
  if (e.isRetryable) {
    // Safe to retry
  }
}

Testing

Use test API keys (pk_test_...) during development:

final micropay = Micropay(
  publicKey: 'pk_test_your_test_key',
  debug: true,
);

// Test phone numbers:
// 254700000001 - Always succeeds
// 254700000002 - Always fails
// 254700000003 - Delays 30s then succeeds

Production Checklist

• Replace test key with live key (pk_live_...)
• Set debug: false
• Implement proper error handling
• Add retry logic for network failures
• Test on real devices with real M-Pesa accounts
• Configure webhook endpoints for server-side verification

Minimum Requirements

• Flutter >= 3.10.0
• Dart >= 3.0.0
• iOS >= 12.0
• Android >= API 21 (Lollipop)

License

MIT