📱 QRIS Decoder

Package TypeScript/JavaScript untuk decode, convert, dan generate QRIS (QR Code Indonesian Standard).

✨ Features

• 🔍 Decode - Decode gambar QRIS ke data terstruktur
• 🔄 Convert - Convert QRIS statis ke dinamis dengan nominal
• 🖼️ Generate - Generate gambar QR dari QRIS string
• ✅ Validasi - Otomatis validasi format QRIS
• 📦 TypeScript - Full TypeScript support dengan type definitions

📦 Installation

npm install qris-decoder

🚀 Quick Start

import { decodeQRIS, convertToDynamic, generateQRIS } from 'qris-decoder';

// 1. Decode gambar QRIS
const decoded = await decodeQRIS('qris.png');
console.log(decoded.data.merchantName); // "Toko ABC"

// 2. Convert ke dynamic dengan nominal
const converted = await convertToDynamic('qris.png', { 
  amount: 50000,
  merchantName: 'Warung Baru' // optional
});

// 3. Generate gambar QR
const generated = await generateQRIS(
  converted.data.converted.raw, 
  'output.png'
);

📖 API Reference

1. decodeQRIS(source)

Decode gambar QRIS dan return data terstruktur.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | source | string \| Buffer | Path file, URL, Buffer, atau base64 |

Returns: Promise<DecodeResult>

const result = await decodeQRIS('qris.png');

// Success
{
  success: true,
  data: {
    raw: "00020101...",
    merchantName: "Toko ABC",
    merchantCity: "Jakarta",
    isStatic: true,
    isDynamic: false,
    transactionAmount: undefined,
    paymentProvider: "Dana",
    // ... more fields
  }
}

// Error
{
  success: false,
  error: "Not a valid QRIS format (must start with 000201)"
}

2. convertToDynamic(source, options)

Convert QRIS statis ke dinamis dengan nominal.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | source | string \| Buffer | Path file, URL, Buffer, base64, atau QRIS string | | options.amount | number \| string | Nominal transaksi (wajib) | | options.merchantName | string | Ganti nama merchant (max 25 char) | | options.merchantCity | string | Ganti kota (max 15 char) | | options.referenceLabel | string | Nomor referensi | | options.billNumber | string | Nomor tagihan |

Returns: Promise<ConvertResult>

// Basic
const result = await convertToDynamic('qris.png', {
  amount: 50000
});

// Dengan custom merchant
const result = await convertToDynamic('qris.png', {
  amount: 75000,
  merchantName: 'Warung Sederhana',
  merchantCity: 'Bandung',
  referenceLabel: 'INV-001'
});

// Response
{
  success: true,
  data: {
    original: { ... },    // Data QRIS asli
    converted: {          // Data QRIS hasil convert
      raw: "00020101021226...",
      merchantName: "Warung Sederhana",
      transactionAmount: "75000",
      isDynamic: true,
      // ...
    }
  }
}

3. generateQRIS(qrisString, outputPath?, options?)

Generate gambar QR code dari QRIS string.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | qrisString | string | QRIS string | | outputPath | string | Path output file (optional) | | options.size | number | Ukuran pixels (default: 500) | | options.margin | number | Margin modules (default: 4) | | options.errorCorrectionLevel | 'L' \| 'M' \| 'Q' \| 'H' | Error correction (default: 'M') |

Returns: Promise<GenerateResult>

// Generate dan simpan ke file
const result = await generateQRIS(qrisString, 'output.png');

// Generate tanpa file (hanya dataUrl)
const result = await generateQRIS(qrisString);

// Response
{
  success: true,
  data: {
    file: "output.png",
    dataUrl: "data:image/png;base64,...",
    qrisString: "00020101...",
    parsed: { ... }
  }
}

📊 QRISInfo Fields

| Field | Type | Description | |-------|------|-------------| | raw | string | QRIS string mentah | | crcValid | boolean | Status CRC checksum | | merchantName | string | Nama merchant | | merchantCity | string | Kota merchant | | countryCode | string | Kode negara (ID) | | isStatic | boolean | True jika QRIS statis | | isDynamic | boolean | True jika QRIS dinamis | | transactionAmount | string | Nominal (hanya dynamic) | | transactionCurrency | string | Kode mata uang (360 = IDR) | | paymentProvider | string | Dana, GoPay, OVO, dll | | merchantAccounts | array | Detail akun merchant |

⚠️ Error Handling

Semua fungsi return object dengan success: boolean:

const result = await decodeQRIS('image.png');

if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error);
  // "Image file not found: image.png"
  // "Not a valid QRIS format (must start with 000201)"
  // "No QR code found in the image"
}

🔧 Supported Providers

• Dana
• GoPay
• OVO
• ShopeePay
• LinkAja
• BCA
• BNI
• BRI
• Mandiri
• Dan lainnya...

📋 Requirements

• Node.js >= 16.0.0

📄 License

MIT © 2024