PixBrcode

Generate, parse and validate Pix "copia e cola" payloads (BR Code), the text behind every Pix QR code.

• Static payloads (key, optional amount, txid, description)
• Dynamic payloads (URL provided by the receiver's bank)
• Parsing into a struct, with CRC16 check
• Key format validation (CPF, CNPJ, phone, e-mail, random key/EVP)
• Zero runtime dependencies

Installation

def deps do
  [
    {:pix_brcode, "~> 0.1.0"}
  ]
end

Usage

Static payload

PixBrcode.encode(%{
  key: "pix@bcb.gov.br",
  merchant_name: "Fulano de Tal",
  merchant_city: "Brasília",
  amount: 1050,        # integer cents, or the string "10.50"
  txid: "ORDER42",     # optional, defaults to "***"
  description: "Thanks" # optional
})
#=> {:ok, "00020126...6304XXXX"}

• merchant_name (max 25 chars) and merchant_city (max 15 chars) have their accents removed ("Brasília" becomes "Brasilia"). Longer values return an error; they are never truncated.
• amount never goes through floats: pass integer cents (1050) or a string with exactly two decimals ("10.50").
• key must follow the formats of the Central Bank's DICT: "12345678901" (CPF), "12345678901234" (CNPJ), "+5561998765432" (phone), lowercase e-mail, or lowercase UUID (EVP).

Dynamic payload

PixBrcode.encode_dynamic(%{
  url: "pix.example.com/qr/v2/9d36b84f",  # without https://
  merchant_name: "Fulano de Tal",
  merchant_city: "Brasilia"
})

Parsing and validating

PixBrcode.decode("00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D")
#=> {:ok,
#=>  %PixBrcode.Payload{
#=>    type: :static,
#=>    key: "123e4567-e12b-12d1-a456-426655440000",
#=>    merchant_name: "Fulano de Tal",
#=>    merchant_city: "BRASILIA",
#=>    txid: "***",
#=>    amount: nil, description: nil, url: nil
#=>  }}

PixBrcode.valid?("not a pix")
#=> false

decode/1 checks the CRC, the structure, the br.gov.bcb.pix GUI and the key format. Leading/trailing whitespace is ignored.

Errors

All functions return {:ok, result} or {:error, reason}:

Reason	When
:missing_required_fields	a required field is missing or is not a string
:invalid_key	key does not match any DICT format
:invalid_merchant_name / :invalid_merchant_city	empty, too long, or not printable ASCII after removing accents
:invalid_description	not a string, or not printable ASCII after removing accents
:invalid_amount	not positive integer cents nor a "10.50" string, or over 13 characters
:invalid_txid	not "***" nor 1–25 letters/digits
:invalid_url	empty or contains a protocol (https://)
{:too_long, id}	field id would exceed 99 characters
:invalid_crc / :invalid_tlv / :invalid_format / :invalid_gui / :missing_key	when decoding

QR code image

Generating the image is out of scope, so any QR code library works. With eqrcode:

{:ok, payload} = PixBrcode.encode(%{key: "pix@bcb.gov.br", merchant_name: "Fulano", merchant_city: "Brasilia"})

svg = payload |> EQRCode.encode() |> EQRCode.svg()

Specification

Based on the Central Bank of Brazil's Manual do BR Code (EMV QRCPS-MPM) and the key formats of the DICT API.

License

MIT. See LICENSE.