upi_parser

pub package License: MIT

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:

Bank SMS Header Codes Resolved Bank Name
SBI SBIBNK, SBIINB, SBIPSG State Bank of India
HDFC HDFCBK, HDFCBN HDFC Bank
ICICI ICICIB, ICICIBK ICICI Bank
Axis AXISBK Axis Bank
Kotak KOTAKB Kotak Mahindra Bank
PNB PNBSMS, PNBBNK Punjab National Bank
BOB BOBTXN, BOBMSG Bank of Baroda
Canara CANBNK Canara Bank
Federal FDRLBN Federal Bank
IndusInd INDUSB IndusInd Bank
Paytm PAYTM Paytm Payments Bank

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.

Libraries

upi_parser