sendkardo-qr

A small JavaScript library for creating Raast payment payloads and ready-to-display QR codes from Pakistani IBANs.

SendKardo performs validation, payload generation, and QR rendering locally. It makes no network requests and works with ESM, CommonJS, and TypeScript.

Independent project. SendKardo is not affiliated with, authorized by, or endorsed by the State Bank of Pakistan or Raast Payments Pakistan (Pvt) Ltd. "Raast" is the name of Pakistan's national instant payment system; it is used here only to describe the publicly published QR payload standard that this library implements.

Install

npm install sendkardo-qr

The QR renderer is included as a dependency, so you do not need to install qrcode separately.

Generate a QR code

Create a PNG data URL that can be used directly as an image source:

import { createRaastQrDataUrl } from "sendkardo-qr";

const qrDataUrl = await createRaastQrDataUrl({
  iban: "PK33ABCD0000000000000000",
  amount: 500
});

In HTML, React, Astro, or another web framework, use the result as an image's src value:

<img src="THE_DATA_URL" alt="Raast payment QR code">

You can also generate an SVG string:

import { createRaastQrSvg } from "sendkardo-qr";

const qrSvg = await createRaastQrSvg({
  iban: "PK33ABCD0000000000000000",
  amount: "500.50",
  expiry: "2026-12-31"
});

Both helpers accept optional rendering settings as their second argument:

const qrDataUrl = await createRaastQrDataUrl(
  { iban: "PK33ABCD0000000000000000", amount: 500 },
  {
    width: 320,
    margin: 2,
    color: { dark: "#01411C", light: "#FFFFFFFF" }
  }
);

QR codes default to 900 × 900 pixels, a four-module quiet zone, and high error correction.

Usage

Generate only the payload

The lower-level payload API remains available when you want to use a different QR renderer:

import { createRaastPayload } from "sendkardo-qr";

const payload = createRaastPayload({
  iban: "PK33ABCD0000000000000000",
  amount: "5000.50",
  expiry: "2026-12-31T18:30"
});

CommonJS

const {
  createRaastPayload,
  createRaastQrDataUrl,
  createRaastQrSvg
} = require("sendkardo-qr");

API

createRaastPayload(options)

Creates a payload string from:

• iban — required Pakistani IBAN; spaces and letter casing are normalized.
• amount — optional positive number or numeric string with up to two decimal places.
• expiry — optional YYYY-MM-DD or YYYY-MM-DDTHH:mm value.

Amount rules

Amounts must be positive, contain only digits with an optional decimal point, and use no more than two decimal places. Commas are accepted and removed during normalization. The normalized value may contain at most 10 characters.

| Amount | Valid? | Result or reason | | --- | --- | --- | | 4 | Yes | 4 | | 4.2 | Yes | 4.2 | | 4.22 | Yes | 4.22 | | "4.20" | Yes | 4.20 | | "5,000.50" | Yes | 5000.50 | | 0.01 | Yes | 0.01 | | 4.2222222 | No | More than two decimal places | | .50 | No | A digit is required before the decimal point | | 4. | No | At least one digit is required after the decimal point | | 0 | No | The amount must be positive | | -4.22 | No | Negative amounts are not accepted | | "Rs 500" | No | Currency text and symbols are not accepted |

With two decimal places, the largest accepted amount is 9999999.99. Whole-number and one-decimal values can use more digits as long as the normalized string remains within the 10-character limit.

For calculated currency values, prefer a decimal string such as "0.30". JavaScript expressions like 0.1 + 0.2 can produce 0.30000000000000004, which is correctly rejected for having more than two decimal places.

When an amount has no explicit expiry, SendKardo uses the next local calendar day. Date-only expiries are encoded as 23:59. Amount-free payloads remain static and receive no automatic expiry.

The expiry is only a field in the payload. Enforcing it is up to the app that scans the code, and some banking apps ignore it and will still scan the QR after the date has passed. Do not rely on the expiry as a security control; treat any QR code you distribute as valid indefinitely.

Invalid input throws SendKardoError with a machine-readable code.

createRaastQrDataUrl(options, qrOptions?)

Creates the Raast payload and renders it as a PNG data URL. It returns a Promise<string>.

createRaastQrSvg(options, qrOptions?)

Creates the Raast payload and renders it as an SVG string. It returns a Promise<string>.

The optional QR settings support width, margin, scale, version, maskPattern, errorCorrectionLevel, and custom dark and light colors.

Other exports

• isValidPakistaniIban(value) validates Pakistani IBAN structure and checksum.
• normalizePakistaniIban(value) removes spaces and uppercases the value.
• normalizeAmount(value) returns a payload-ready amount, an empty string when omitted, or null when invalid.
• getDefaultExpiry(now) returns the next local calendar day as YYYY-MM-DD.
• crc16(value) calculates the CRC-16 checksum used by the payload.
• ERROR_CODES and SendKardoError support programmatic error handling.

The package supports ESM, CommonJS, and TypeScript and performs no network requests.

Built by Umar.