ITC SUNMI Card Reader #

A Flutter plugin that provides card reading functionality for SUNMI POS devices. This plugin enables EMV card processing, data extraction, and seamless integration with SUNMI's hardware capabilities.

⚠️ Important Notice #

This plugin ONLY works on SUNMI Android devices. It will not function on regular Android devices, iOS devices, or other POS terminals. Please ensure you are using a SUNMI device before implementing this plugin.

Features #

✅ Card Scanning - Support for EMV chip cards, magnetic stripe cards, and contactless payments
✅ Data Extraction - Extract card number, expiry date, cardholder name, and service codes
✅ Track Data - Access to Track 1 and Track 2 data
✅ EMV Processing - Full EMV transaction support with app selection
✅ Real-time Callbacks - Status updates during the card reading process
✅ Multiple Card Types - Supports Visa, MasterCard, UnionPay, Amex, JCB, RuPay
✅ Error Handling - Comprehensive error management and recovery

Supported SUNMI Devices #

SUNMI P2 series
SUNMI P2 Pro
SUNMI P2 Lite
SUNMI V2 series
Other SUNMI POS terminals with card reading capabilities

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  itc_sunmi_card_reader: ^1.0.0

Then run:

flutter pub get

Platform Setup #

Android Requirements #

Min SDK: 21 (Android 5.0)
Target SDK: 34
Device: SUNMI POS terminal only

The plugin automatically adds required SUNMI permissions. No additional setup needed.

Usage #

Basic Usage #

import 'package:itc_sunmi_card_reader/itc_sunmi_card_reader.dart';

// Simple card scan
final result = await ItcSunmiCardReaderService.startCardScan(amount: 25.50);

if (result != null) {
  print('Card Number: ${result.cardNumber}');
  print('Expiry Date: ${result.expiryDate}');
  print('Cardholder: ${result.cardholderName}');
  print('Card Type: ${result.cardType}');
} else {
  print('Scan cancelled or failed');
}

With Status Updates #

import 'package:itc_sunmi_card_reader/itc_sunmi_card_reader.dart';

Future<void> scanCard() async {
  try {
    final result = await ItcSunmiCardReaderService.startCardScan(
      amount: 50.00,
      onStatusUpdate: (status) {
        print('Status: $status');
        // Update your UI with scan progress
      },
      onCardDetected: (cardType) {
        print('Card detected: $cardType');
        // Show detected card type to user
      },
    );

    if (result != null) {
      print('Scan successful!');
      print('Card: ${result.cardNumber}');
      print('Expiry: ${result.expiryDate}');
      print('Name: ${result.cardholderName}');
      print('Track 1: ${result.track1}');
      print('Track 2: ${result.track2}');
    }
  } catch (e) {
    print('Error: $e');
  }
}

Handling App Selection #

Future<void> scanCardWithAppSelection() async {
  try {
    final result = await ItcSunmiCardReaderService.startCardScan(
      amount: 100.00,
      onAppSelectionRequired: (apps, selectApp) {
        // Show dialog for user to select payment app
        showDialog(
          context: context,
          builder: (context) => AlertDialog(
            title: Text('Select Payment App'),
            content: Column(
              mainAxisSize: MainAxisSize.min,
              children: apps.asMap().entries.map((entry) {
                return ListTile(
                  title: Text(entry.value),
                  onTap: () {
                    Navigator.pop(context);
                    selectApp(entry.key); // Select the app
                  },
                );
              }).toList(),
            ),
          ),
        );
      },
    );

    if (result != null) {
      // Process payment with selected app
      processPayment(result);
    }
  } catch (e) {
    handleError(e);
  }
}

Complete Example #

import 'package:flutter/material.dart';
import 'package:itc_sunmi_card_reader/itc_sunmi_card_reader.dart';

class PaymentScreen extends StatefulWidget {
  @override
  _PaymentScreenState createState() => _PaymentScreenState();
}

class _PaymentScreenState extends State<PaymentScreen> {
  CardScanResult? _scanResult;
  bool _isScanning = false;
  String _scanStatus = '';

  Future<void> _startCardScan() async {
    // Check if device supports card reading
    if (!ItcSunmiCardReaderService.isSupported) {
      _showSnackBar('Card reading not supported on this device', Colors.red);
      return;
    }

    setState(() {
      _isScanning = true;
      _scanStatus = 'Initializing...';
      _scanResult = null;
    });

    try {
      final result = await ItcSunmiCardReaderService.startCardScan(
        amount: 25.50,
        onStatusUpdate: (status) {
          setState(() {
            _scanStatus = status;
          });
        },
        onCardDetected: (cardType) {
          setState(() {
            _scanStatus = '$cardType card detected - Processing...';
          });
        },
        onAppSelectionRequired: (apps, selectApp) {
          _showAppSelectionDialog(apps, selectApp);
        },
      );

      setState(() {
        _isScanning = false;
        _scanResult = result;
      });

      if (result != null) {
        _showSnackBar('Card scanned successfully!', Colors.green);
      } else {
        _showSnackBar('Scan cancelled', Colors.orange);
      }
    } catch (e) {
      setState(() {
        _isScanning = false;
        _scanStatus = '';
      });
      _showSnackBar('Error: ${e.toString()}', Colors.red);
    }
  }

  void _showAppSelectionDialog(List<String> apps, Function(int) selectApp) {
    showDialog(
      context: context,
      barrierDismissible: false,
      builder: (context) => AlertDialog(
        title: Text('Select Payment App'),
        content: Column(
          mainAxisSize: MainAxisSize.min,
          children: apps.asMap().entries.map((entry) {
            return ListTile(
              title: Text(entry.value),
              onTap: () {
                Navigator.pop(context);
                selectApp(entry.key);
              },
            );
          }).toList(),
        ),
      ),
    );
  }

  void _showSnackBar(String message, Color color) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        backgroundColor: color,
        duration: Duration(seconds: 3),
      ),
    );
  }

  Future<void> _stopScan() async {
    try {
      await ItcSunmiCardReaderService.stopCardScan();
      setState(() {
        _isScanning = false;
        _scanStatus = '';
      });
      _showSnackBar('Scan cancelled', Colors.orange);
    } catch (e) {
      print('Error stopping scan: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('SUNMI Card Reader'),
        backgroundColor: Colors.blue,
      ),
      body: Padding(
        padding: EdgeInsets.all(20.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            // Amount Display
            Container(
              padding: EdgeInsets.all(20),
              decoration: BoxDecoration(
                color: Colors.blue.withOpacity(0.1),
                borderRadius: BorderRadius.circular(12),
                border: Border.all(color: Colors.blue.withOpacity(0.3)),
              ),
              child: Column(
                children: [
                  Text(
                    'Amount to Charge',
                    style: TextStyle(fontSize: 16, color: Colors.grey[600]),
                  ),
                  SizedBox(height: 8),
                  Text(
                    'GH₵ 25.50',
                    style: TextStyle(
                      fontSize: 32,
                      fontWeight: FontWeight.bold,
                      color: Colors.blue,
                    ),
                  ),
                ],
              ),
            ),

            SizedBox(height: 30),

            // Scan Button
            SizedBox(
              height: 54,
              child: ElevatedButton.icon(
                onPressed: _isScanning ? null : _startCardScan,
                icon: _isScanning
                    ? SizedBox(
                        width: 20,
                        height: 20,
                        child: CircularProgressIndicator(
                          strokeWidth: 2,
                          valueColor: AlwaysStoppedAnimation<Color>(Colors.white),
                        ),
                      )
                    : Icon(Icons.credit_card, color: Colors.white),
                label: Text(
                  _isScanning ? 'Scanning...' : 'Scan Card',
                  style: TextStyle(fontSize: 18, color: Colors.white),
                ),
                style: ElevatedButton.styleFrom(
                  backgroundColor: Colors.blue,
                  shape: RoundedRectangleBorder(
                    borderRadius: BorderRadius.circular(12),
                  ),
                ),
              ),
            ),

            SizedBox(height: 16),

            // Cancel Button (only show when scanning)
            if (_isScanning)
              SizedBox(
                height: 48,
                child: OutlinedButton(
                  onPressed: _stopScan,
                  child: Text('Cancel Scan'),
                  style: OutlinedButton.styleFrom(
                    side: BorderSide(color: Colors.red),
                    foregroundColor: Colors.red,
                  ),
                ),
              ),

            SizedBox(height: 20),

            // Scan Status
            if (_isScanning && _scanStatus.isNotEmpty)
              Container(
                padding: EdgeInsets.all(16),
                decoration: BoxDecoration(
                  color: Colors.blue.withOpacity(0.1),
                  borderRadius: BorderRadius.circular(8),
                ),
                child: Row(
                  children: [
                    SizedBox(
                      width: 16,
                      height: 16,
                      child: CircularProgressIndicator(strokeWidth: 2),
                    ),
                    SizedBox(width: 12),
                    Expanded(
                      child: Text(
                        _scanStatus,
                        style: TextStyle(color: Colors.blue[800]),
                      ),
                    ),
                  ],
                ),
              ),

            SizedBox(height: 20),

            // Results Display
            if (_scanResult != null)
              Container(
                padding: EdgeInsets.all(16),
                decoration: BoxDecoration(
                  color: Colors.green.withOpacity(0.1),
                  borderRadius: BorderRadius.circular(12),
                  border: Border.all(color: Colors.green.withOpacity(0.3)),
                ),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Row(
                      children: [
                        Icon(Icons.check_circle, color: Colors.green, size: 20),
                        SizedBox(width: 8),
                        Text(
                          'Card Scan Results',
                          style: TextStyle(
                            fontSize: 18,
                            fontWeight: FontWeight.bold,
                            color: Colors.green,
                          ),
                        ),
                      ],
                    ),
                    SizedBox(height: 16),
                    _buildResultRow('Card Number', 
                        ItcSunmiCardReaderService.formatCardNumber(_scanResult!.cardNumber)),
                    _buildResultRow('Card Type', _scanResult!.cardType),
                    if (_scanResult!.expiryDate.isNotEmpty)
                      _buildResultRow('Expiry Date', 
                          ItcSunmiCardReaderService.formatExpiryDate(_scanResult!.expiryDate)),
                    if (_scanResult!.cardholderName.isNotEmpty)
                      _buildResultRow('Cardholder', _scanResult!.cardholderName),
                    if (_scanResult!.serviceCode.isNotEmpty)
                      _buildResultRow('Service Code', _scanResult!.serviceCode),
                    if (_scanResult!.track1.isNotEmpty)
                      _buildResultRow('Track 1', _scanResult!.track1, isLong: true),
                    if (_scanResult!.track2.isNotEmpty)
                      _buildResultRow('Track 2', _scanResult!.track2, isLong: true),
                  ],
                ),
              ),

            SizedBox(height: 20),

            // Clear Results Button
            if (_scanResult != null)
              OutlinedButton(
                onPressed: () {
                  setState(() {
                    _scanResult = null;
                  });
                },
                child: Text('Clear Results'),
              ),
          ],
        ),
      ),
    );
  }

  Widget _buildResultRow(String label, String value, {bool isLong = false}) {
    return Padding(
      padding: EdgeInsets.only(bottom: 8),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            '$label:',
            style: TextStyle(
              fontSize: 12,
              fontWeight: FontWeight.w500,
              color: Colors.grey[600],
            ),
          ),
          SizedBox(height: 2),
          Text(
            value.isNotEmpty ? value : 'N/A',
            style: TextStyle(
              fontSize: isLong ? 10 : 14,
              fontWeight: FontWeight.w600,
              color: Colors.black87,
            ),
            maxLines: isLong ? 2 : 1,
            overflow: TextOverflow.ellipsis,
          ),
        ],
      ),
    );
  }
}

API Reference #