Raast QR Code Generator

A JavaScript library for generating Raast payment QR codes compliant with Pakistani banking standards.

Installation

npm install raast

Usage

This library uses neverthrow for type-safe error handling. All functions return ResultAsync objects instead of throwing errors.

Generating a Static QR Code

Static QR codes are reusable and don't contain payment amounts:

import { generatePaymentQrCode } from 'raast';

const result = await generatePaymentQrCode({
  "qr-code-type": "static",
  iban: "PK36SCBL0000001123456702"
});

if (result.isOk()) {
  console.log(result.value.dataUri); // Data URI containing the QR code image
} else {
  console.error(`Error ${result.error.code}: ${result.error.message}`);
  if (result.error.hint) {
    console.log(`Hint: ${result.error.hint}`);
  }
}

Generating a Dynamic QR Code

Dynamic QR codes include amount, description, and expiration:

import { generatePaymentQrCode } from 'raast';

const result = await generatePaymentQrCode({
  "qr-code-type": "dynamic",
  iban: "PK36SCBL0000001123456702",
  amount: "1000.00",
  description: "Payment for services",
  expiration: "2024-12-31T23:59:59"
});

// Using the match pattern for clean error handling
result.match(
  (qrCode) => console.log(qrCode.dataUri),
  (error) => console.error(`${error.code}: ${error.message}`)
);

API

generatePaymentQrCode(data)

Generates a Raast payment QR code.

Parameters

• data (Object): QR code configuration
  • qr-code-type (string): Either "static" or "dynamic"
  • iban (string): IBAN account number (required)
  • amount (string): Payment amount (required for dynamic QR codes)
  • description (string): Payment description (optional)
  • expiration (string): ISO 8601 date/time string (required for dynamic QR codes)

Returns

Promise<ResultAsync<QrCodeResult, QrCodeError>>

Success value (QrCodeResult):

• dataUri (string): Data URI containing the QR code image

Error value (QrCodeError):

• code (string): Error code for programmatic handling (e.g., MISSING_IBAN, INVALID_AMOUNT_TYPE)
• message (string): Human-readable error message
• field (string): Field that caused the error
• hint (string): Helpful suggestion to fix the error
• Additional context-specific fields (e.g., value, length, maxLength)

Error Codes

• MISSING_IBAN: IBAN is required
• INVALID_IBAN_TYPE: IBAN must be a string
• IBAN_TOO_LONG: IBAN exceeds 99 characters
• MISSING_AMOUNT: Amount required for dynamic QR codes
• INVALID_AMOUNT_TYPE: Amount must be a string
• AMOUNT_TOO_LONG: Amount exceeds 99 characters
• MISSING_EXPIRATION: Expiration required for dynamic QR codes
• INVALID_DESCRIPTION_TYPE: Description must be a string
• DESCRIPTION_TOO_LONG: Description exceeds 99 characters
• INVALID_CHARACTER: Invalid character in payload
• QR_GENERATION_FAILED: QR code library error

TypeScript Support

This package includes TypeScript type definitions. Types are automatically available when using TypeScript:

import { generatePaymentQrCode, QrCodeData, QrCodeResult } from 'raast';

const data: QrCodeData = {
  "qr-code-type": "static",
  iban: "PK36SCBL0000001123456702"
};

const result: QrCodeResult = await generatePaymentQrCode(data);

Compatibility

This package supports Raast QR codes for Pakistani mobile banking applications. For a compatibility matrix showing which banking apps support different QR code features, see compatibility.json.

License

MIT