@thiagoprazeres/pix-static-brcode

Generate, parse and validate Brazilian Pix static BR Code (EMV QRCPS-MPM) — CRC-16/CCITT included, zero runtime dependencies.

Implements the Manual do BR Code and Manual de Padrões para Iniciação do Pix published by BACEN.

Install

npm install @thiagoprazeres/pix-static-brcode

Usage

Generate

import {
  generateStaticBrCode,
  projectReceiverName,
  projectCity,
  buildBrCodeRef,
} from '@thiagoprazeres/pix-static-brcode';

const payload = generateStaticBrCode({
  pixKey: '11999998888',
  receiverName: projectReceiverName('João da Silva'),  // → 'JOAO DA SILVA'
  receiverCity: projectCity('São Paulo'),               // → 'SAO PAULO'
  referenceLabel: buildBrCodeRef(crypto.randomUUID()),
  amount: 99.90,
  description: 'Pedido #1234',
});
// → '000201...<EMV payload>...6304XXXX'

Parse

import { parseStaticBrCode } from '@thiagoprazeres/pix-static-brcode';

const parsed = parseStaticBrCode(payload);
// {
//   pixKey: '11999998888',
//   receiverName: 'JOAO DA SILVA',
//   receiverCity: 'SAO PAULO',
//   referenceLabel: '...',
//   amount: 99.90,
//   description: 'Pedido #1234'
// }

Throws Error if the payload is malformed or the CRC-16 checksum is invalid.

Validate

import { validateCrc16, isValidBrCode } from '@thiagoprazeres/pix-static-brcode';

validateCrc16(payload); // true / false — checksum only
isValidBrCode(payload); // true / false — full validation, never throws

API

generateStaticBrCode(params: BrCodeParams): string

Generates a static Pix BR Code EMV payload with CRC-16/CCITT checksum.

interface BrCodeParams {
  pixKey: string;         // CPF, CNPJ, email, phone or EVP
  receiverName: string;   // already projected (no accents, uppercase, max 25)
  receiverCity: string;   // already projected (no accents, uppercase, max 15)
  referenceLabel: string; // max 25 alphanumeric chars
  amount?: number;        // omit for open-value charges
  description?: string;
}

parseStaticBrCode(payload: string): ParsedBrCode

Parses a static BR Code payload. Validates CRC-16 before parsing. Throws on invalid input.

interface ParsedBrCode {
  pixKey: string;
  receiverName: string;
  receiverCity: string;
  referenceLabel?: string;
  amount?: number;
  description?: string;
}

validateCrc16(payload: string): boolean

Returns true if the last 4 chars match the CRC-16/CCITT checksum of the rest. Never throws.

isValidBrCode(payload: string): boolean

Full validation (CRC + required fields). Never throws.

Projections

projectReceiverName(name: string): string
// Remove accents, strip non-alphanumeric, uppercase, truncate to 25 chars

projectCity(city: string): string
// Remove accents, strip non-alphanumeric, uppercase, truncate to 15 chars

buildBrCodeRef(id: string): string
// Strip hyphens from UUID, uppercase, truncate to 25 chars

EMV field map

| Tag | Field | Value | |-----|-------|-------| | 00 | Payload Format Indicator | 01 | | 26 | Merchant Account Info | br.gov.bcb.pix + key + description | | 52 | Merchant Category Code | 0000 | | 53 | Transaction Currency | 986 (BRL) | | 54 | Transaction Amount | omitted if open-value | | 58 | Country Code | BR | | 59 | Merchant Name | projected receiver name | | 60 | Merchant City | projected city | | 62/05 | Reference Label | charge reference | | 63 | CRC-16/CCITT | 4-char hex checksum |

Motivation

Generating a valid Pix static BR Code requires correct EMV TLV encoding, specific field ordering, string normalization per BACEN spec, and a CRC-16/CCITT checksum. No standalone, zero-dependency package covered all three aspects (generation, parsing, and CRC validation) before this one.

Scope

• Generates static Pix BR Code payloads per BACEN spec
• Parses static BR Code payloads back to structured objects
• Validates CRC-16/CCITT checksums
• Normalizes receiver name, city, and reference label per spec

Out of scope

• Does not generate QR Code images (use a QR library on top)
• Does not validate Pix key format semantically (CPF checksum, email format, etc.)
• Does not handle dynamic BR Code / Pix cobrança com vencimento
• Does not make any network requests

References

• Manual do BR Code (BACEN)
• Manual de Padrões para Iniciação do Pix (BACEN)
• CRC-16 validation discussion — bacen/pix-api #189

License

Apache 2.0