pix-utils

Pix-Utils

Pix-Utils is a set of tools to parse, generate and validate payments of Brazil Instant Payment System (Pix), making fast and simple to handle charges and proccess then in your project.

🚀 Usage

Install the package in your project

yarn add pix-utils

Create Static Pix

import { createStaticPix, hasError } from 'pix-utils';

const pix = createStaticPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  pixKey: '[e-mail]',
  infoAdicional: 'Gerado por Pix-Utils',
  transactionAmount: 1,
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  // [e-mail]0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6009Sao Paulo62070503***63046069
}

Create Dynamic Pix

import { createDynamicPix, hasError } from 'pix-utils';

const pix = createDynamicPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  url: 'https://pix.thalesogliari.com.br',
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  // 00020126540014br.gov.bcb.pix2532https://pix.thalesogliari.com.br5204000053039865802BR5914Thales Ogliari6009SAO PAULO62070503***63043FD3
}

Throw errors

By default, pix-utils wont throw an error when parsing an invalid pix, but you can enable it by using the throwIfError function.

import { createDynamicPix } from 'pix-utils';

const pix = createDynamicPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  url: 'https://pix.thalesogliari.com.br',
}).throwIfError();

const brCode = pix.toBRCode();
// 00020126540014br.gov.bcb.pix2532https://pix.thalesogliari.com.br5204000053039865802BR5914Thales Ogliari6009SAO PAULO62070503***63043FD3

Parse BRCode

const pix = parsePix(
  '[e-mail]0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6015SAO MIGUEL DO O62070503***6304059A'
);

// {
//   type: 'STATIC',
//   merchantCategoryCode: '0000',
//   transactionCurrency: '986',
//   countryCode: 'BR',
//   merchantName: 'Thales Ogliari',
//   merchantCity: 'SAO MIGUEL DO O',
//   pixKey: '[e-mail]',
//   transactionAmount: 1,
//   infoAdicional: 'Gerado por Pix-Utils',
//   txid: '***',
//   toBRCode: [Function: toBRCode],
//   toImage: [Function: toImage]
// }

Export to Base64 Image

const pix = parsePix(
  '[e-mail]0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6015SAO MIGUEL DO O62070503***6304059A'
);

pix.toImage();
// data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4iNAAAAAklEQVR4AewaftIAAAwHSURBVO3BQW4sy7LgQDKh/W...

🍰 Contributing

Please contribute using GitHub Flow. Create a branch, add commits, and open a pull request.

📝 License

This project is under MIT license.

Developed with 💚 by @thalesog 🇧🇷

Changelog

2.8.2 (2025-08-15)

Bug Fixes

• make objeto property optional in PIXRecPayload type (#37) (a3227c1)