VietQR.dart

A comprehensive Dart ecosystem for VietQR (Vietnamese QR Payment Standard) - EMVCo compliant QR code generation, rendering, and image export.

🚀 Quick Start

Choose the package that fits your needs:

• Flutter App: Use vietqr_widget for beautiful QR UI widgets
• Image Generation: Use vietqr_image for PNG/JPEG export
• Core Logic: Use vietqr_core for encoding/decoding

dependencies:
  vietqr_widget: ^0.1.1    # Flutter UI widgets
  vietqr_image: ^0.1.0     # Image generation  
  vietqr_core: ^0.2.3      # Core encoding/decoding

📦 Packages Overview

This monorepo contains three complementary packages that work together to provide a complete VietQR solution:

🧠 vietqr_core

The foundation - Pure Dart library for VietQR data encoding and decoding.

• ✅ Pure Dart - Works everywhere (Flutter, web, server, CLI)
• ✅ 18+ Vietnamese banks - Built-in support for major banks
• ✅ EMVCo compliant - Follows international standards
• ✅ Type-safe - Strong typing with validation
• ✅ Encode & Decode - Full bidirectional support

import 'package:vietqr_core/vietqr_core.dart';

final payment = VietQrData(
  bankBinCode: SupportedBank.vietcombank,
  bankAccount: '0123456789',
  amount: '50000',
  merchantName: 'Coffee Shop',
);

final qrString = VietQr.encode(payment);

🎨 vietqr_widget

For Flutter apps - Beautiful, customizable QR code widgets.

• ✅ Easy Integration - Drop-in Flutter widget
• ✅ Customizable - Colors, embedded images, error handling
• ✅ Responsive - Adapts to different screen sizes
• ✅ Built-in validation - Automatic error handling

import 'package:vietqr_widget/vietqr_widget.dart';

VietQrWidget(
  data: payment,
  embeddedImage: EmbeddedImage(
    image: AssetImage('assets/logo.png'),
  ),
)

🖼️ vietqr_image

For image generation - Export QR codes as PNG, JPEG, or other formats.

• ✅ Multiple formats - PNG, JPEG, WebP support
• ✅ Server-side - Perfect for backend services
• ✅ Customizable - Size, colors, error correction
• ✅ Memory efficient - Optimized for batch processing

import 'package:vietqr_image/vietqr_image.dart';

final imageBytes = await VietQrImage.generatePng(
  data: payment,
  size: 512,
);

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   vietqr_widget │    │   vietqr_image  │    │     Your App    │
│                 │    │                 │    │                 │
│  Flutter UI     │    │  Image Export   │    │   Custom Logic  │
│  Components     │    │  PNG/JPEG/etc   │    │                 │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                   ┌─────────────▼───────────┐
                   │       vietqr_core       │
                   │                         │
                   │  • VietQR Encoding      │
                   │  • VietQR Decoding      │
                   │  • Bank Support         │
                   │  • Data Validation      │
                   │  • EMVCo Compliance     │
                   └─────────────────────────┘

🏦 Supported Banks

All packages support 18+ major Vietnamese banks including:

Bank	BIN Code	Bank	BIN Code
Vietcombank	970436	MB Bank	970422
Vietinbank	970415	ACB	970416
BIDV	970418	VPBank	970432
Agribank	970405	Sacombank	970403
Techcombank	970407	TPBank	970423

View all supported banks →

🌟 Use Cases

🏪 E-commerce & Retail

// Dynamic QR for product checkout
final productPayment = VietQrData(
  bankBinCode: SupportedBank.techcombank,
  bankAccount: 'STORE123456',
  merchantName: 'Online Store',
  additional: AdditionalData(
    purpose: 'Product purchase',
    referenceLabel: 'ORDER-${orderId}',
  ),
);

🍕 Restaurants & Food Service

// Table-specific QR codes
final tablePayment = VietQrData(
  bankBinCode: SupportedBank.vietcombank,
  bankAccount: '0123456789',
  merchantName: 'Pho Restaurant',
  additional: AdditionalData(
    purpose: 'Table payment',
    storeLabel: 'Table ${tableNumber}',
  ),
);

💼 Business Invoicing

// Invoice payment QR
final invoicePayment = VietQrData(
  bankBinCode: SupportedBank.bidv,
  bankAccount: 'COMPANY789',
  amount: '1500000',
  merchantName: 'ABC Company Ltd',
  additional: AdditionalData(
    purpose: 'Invoice payment',
    billNumber: 'INV-2024-001',
    customerLabel: 'Client XYZ',
  ),
);

🎫 Event & Ticketing

// Event ticket payment
final ticketPayment = VietQrData(
  bankBinCode: SupportedBank.mbbank,
  bankAccount: 'EVENT456789',
  amount: '299000',
  merchantName: 'Concert Venue',
  additional: AdditionalData(
    purpose: 'Concert ticket',
    referenceLabel: 'TICKET-${ticketId}',
  ),
);

🔧 Development

This project uses Melos for monorepo management.

# Install Melos
dart pub global activate melos

# Bootstrap the workspace
melos bootstrap

# Run tests for all packages
melos test

# Publish all packages
melos publish

Package Commands

# Core package
cd packages/vietqr_core
dart test

# Widget package  
cd packages/vietqr_widget
flutter test

# Image package
cd packages/vietqr_image
dart test

📚 Documentation

• vietqr_core - Core encoding/decoding documentation
• vietqr_widget - Flutter widget usage guide
• vietqr_image - Image generation examples

Technical References

• VietQR Field Definitions
• EMVCo QR Code Specification

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

Made with ❤️ for the Vietnamese developer community

If you find this project helpful, please give it a ⭐ on GitHub!