bysquare_dart library

PAY by square & Invoice by square - Dart implementation.

Encodes and decodes Slovak banking QR codes following the SBA standard (v1.2.0 for PAY, v1.0.0 for Invoice).

Quick start - PAY by square

import 'package:bysquare_dart/bysquare_dart.dart';

// Encode
final qr = payEncode(
  PayDataModel(
    payments: [
      PaymentOrder(
        amount: 19.99,
        currencyCode: 'EUR',
        bankAccounts: [BankAccount(iban: 'SK9611000000002918599669')],
        beneficiary: Beneficiary(name: 'Acme s.r.o.'),
      ),
    ],
  ),
);

// Decode
final model = payDecode(qr);

Quick start - Invoice by square

import 'package:bysquare_dart/bysquare_dart.dart';

final qr = invoiceEncode(
  InvoiceDataModel(
    documentType: InvoiceDocumentType.invoice,
    invoiceId: 'FAK-2024-001',
    issueDate: '20241201',
    localCurrencyCode: 'EUR',
    supplierParty: SupplierParty(
      partyName: 'Acme s.r.o.',
      postalAddress: PostalAddress(
        streetName: 'Hlavná',
        cityName: 'Bratislava',
        postalZone: '81101',
        country: 'SK',
      ),
    ),
    customerParty: CustomerParty(partyName: 'Zákazník a.s.'),
    numberOfInvoiceLines: 3,
    taxCategorySummaries: [
      TaxCategorySummary(
        classifiedTaxCategory: 0.20,
        taxExclusiveAmount: 100,
        taxAmount: 20,
      ),
    ],
    monetarySummary: MonetarySummary(),
  ),
);

Classes

BankAccount
IBAN + optional BIC of a payment recipient.
Beneficiary
Beneficiary (payment recipient) identification.
Contact
CustomerParty
DirectDebit
A direct debit payment.
DirectDebitScheme
Direct debit scheme.
DirectDebitType
Direct debit type.
InvoiceDataModel
Root data model for an Invoice by square QR code.
InvoiceDocumentType
Invoice document sub-types within bysquareType=1.
InvoiceEncodeOptions
Options for invoiceEncode.
MonetarySummary
Month
Months as bit-flag constants. Combine with bitwise OR (or plain addition) for standing orders that span multiple months.
PayDataModel
Root data model for a PAY by square QR code.
PayEncodeOptions
Options for payEncode.
Payment
Base class for all payment types.
PaymentMean
Payment means as bit-flag constants. Combine with bitwise OR.
PaymentOptions
Payment type classifier.
PaymentOrder
A single, one-time payment order.
Periodicity
Periodicity of a standing order.
PostalAddress
SingleInvoiceLine
StandingOrder
A recurring (standing order) payment.
SupplierParty
TaxCategorySummary
Version
Bysquare format version encoded in the QR header (4-bit field).

Functions

base32hexDecode(String input, {bool loose = false}) → Uint8List
Decodes a Base32Hex input string back to bytes.
base32hexEncode(List<int> input, {bool addPadding = true}) → String
Encodes input bytes to a Base32Hex string.
crc32(String data) → int
Computes the CRC32 checksum of data encoded as UTF-8.
deburr(String text) → String
Removes diacritics from text by:
decodeOptions(int sum) → List<int>
Decodes a summed classifier value back into individual flag values.
encodeOptions(List<int> options) → int
Encodes multiple classifier options into a single integer by summing them.
invoiceDecode(String qr) → InvoiceDataModel
Decodes a Base32Hex qr string into an InvoiceDataModel.
invoiceDeserialize(String tabString, int documentType) → InvoiceDataModel
Deserializes the tab-separated tabString back into an InvoiceDataModel.
invoiceEncode(InvoiceDataModel model, [InvoiceEncodeOptions options = const InvoiceEncodeOptions()]) → String
Encodes an InvoiceDataModel into a Base32Hex QR string.
invoiceSerialize(InvoiceDataModel data) → String
Serializes an InvoiceDataModel to the tab-separated wire format.
payDecode(String qr) → PayDataModel
Decodes a Base32Hex qr string into a PayDataModel.
payDeserialize(String tabString) → PayDataModel
Parses the tab-separated tabString into a PayDataModel.
payEncode(PayDataModel model, [PayEncodeOptions options = const PayEncodeOptions()]) → String
Encodes a PayDataModel into a Base32Hex QR string ready for embedding in a QR code image.
paySerialize(PayDataModel data) → String
Transforms a PayDataModel into the tab-separated intermediate format.
validateBankAccount(BankAccount account, String path) → void
Validates a BankAccount - IBAN and optional BIC.
validateInvoiceDataModel(InvoiceDataModel model) → void
Validates an InvoiceDataModel before encoding.
validatePayDataModel(PayDataModel model, {int version = Version.v120}) → void
Validates the full PayDataModel.
validatePayment(Payment payment, String path, {int version = Version.v120}) → void
Validates a Payment - currency code, dates, bank accounts, and beneficiary name (required since v1.2.0).

Exceptions / Errors

BysquareDecodeError
Thrown when decoding fails due to bad input, checksum mismatch, or unsupported format version.
BysquareEncodeError
Thrown when encoding fails due to invalid header values or oversized payload.
BysquareValidationError
Thrown when a data model field fails validation.