upi_parser #

A high-performance, strongly typed Dart package to parse Indian bank SMS notifications and extract structured UPI transaction details.

Built using a hybrid parsing engine: high-speed RegEx pattern scanners combined with Parsing Expression Grammars (PEGs) powered by PetitParser for strict formatting validation.

Features #

• Automated Scanning: Checks if a message is a UPI notification (isUpiSms).
• Deep Extraction: Parses and extracts:
  • Amount: Numerical transaction value (handles Rs., INR, ₹, and optional actions).
  • Transaction Type: Resolves whether it is a credit (received) or debit (spent) transaction.
  • VPA (UPI ID): Extracts receiver/sender handles (e.g. merchant@ybl, friend@paytm).
  • Account/Card Reference: Identifies masked accounts (XX1234) or credit card suffixes (Card 1111).
  • UPI Ref / UTR Number: Extracts 12-digit transaction index codes.
  • Date: Auto-normalizes various formats (e.g. 04-Jun-26, 17Jan23, 25-09).
  • Bank Identification: Identifies the formal bank name using sender ID or keyword patterns.
• Batch Processing: Filter and parse a list of SMS messages in one call.

Getting Started #

Installation #

Add upi_parser to your pubspec.yaml file:

dependencies:
  upi_parser: ^0.1.0

Or run:

dart pub add upi_parser

Usage Example #

import 'package:upi_parser/upi_parser.dart';

void main() {
  final parser = UpiSmsParser();

  // 1. Check if SMS is a UPI transaction
  const smsText = 'Dear UPI user A/C X9115 debited by 1046.0 on date 19Sep24 trf to FOODAHOLIC Refno 426363998765. -SBI';
  
  if (parser.isUpiSms(smsText)) {
    // 2. Parse the SMS details
    final transaction = parser.parse(smsText, senderId: 'AD-SBIBNK');

    if (transaction != null) {
      print('Amount: ₹${transaction.amount}');          // ₹1046.0
      print('Type: ${transaction.type}');                // TransactionType.debit
      print('VPA: ${transaction.vpa}');                  // null
      print('UPI Ref: ${transaction.upiRefNumber}');     // 426363998765
      print('Bank: ${transaction.bankName}');            // State Bank of India
      print('Account: ${transaction.accountNumber}');    // X9115
      print('Date: ${transaction.date}');                // 2024-09-19
    }
  }
}

Supported Banks #

The parser automatically maps SMS patterns from all major Indian banking headers:

Behind the Scenes: How it works #

The package uses a hybrid approach to ensure both performance and accuracy:

                  ┌────────────────────────┐
                  │      Raw SMS Text      │
                  └───────────┬────────────┘
                              │
                              ▼
                  ┌────────────────────────┐
                  │  RegEx Token Scanner   │  (Isolates field locations)
                  └───────────┬────────────┘
                              │
                              ▼
                  ┌────────────────────────┐
                  │    PetitParser PEG     │  (Strict grammar validation
                  └───────────┬────────────┘   & type conversion)
                              │
                              ▼
                  ┌────────────────────────┐
                  │  UpiTransaction Model  │  (Strongly typed Dart object)
                  └────────────────────────┘

PEGs (Parsing Expression Grammars) are ideal for validating formatting constructs (like complex date normalizations or decimal amount separators) in a type-safe way compared to convoluted RegEx matches.

License #

This project is licensed under the MIT License - see the LICENSE file for details.