PixBrcode (pix_brcode v0.2.0)

Copy Markdown View Source

Generates and reads Pix "copia e cola" payloads (BR Code).

Summary

Types

dynamic_params()

Parameters of encode_dynamic/1.

error()

Reason returned in {:error, reason}.

key_type()

Pix key type, for the :key_type option of encode/1.

params()

Parameters of encode/1.

Functions

decode(payload)

Reads a Pix payload, checking CRC, structure and GUI.

encode(params)

Builds a static Pix payload.

encode_dynamic(params)

Builds a dynamic Pix payload, pointing to a URL provided by the receiver's bank.

valid?(payload)

Returns true if payload decodes successfully.

Types

dynamic_params()

@type dynamic_params() :: %{
  url: String.t(),
  merchant_name: String.t(),
  merchant_city: String.t()
}

Parameters of encode_dynamic/1.

error()

@type error() ::
  :missing_required_fields
  | :invalid_key
  | :invalid_key_type
  | :invalid_merchant_name
  | :invalid_merchant_city
  | :invalid_description
  | :invalid_amount
  | :invalid_txid
  | :invalid_url
  | {:too_long, String.t()}
  | :invalid_crc
  | :invalid_tlv
  | :invalid_format
  | :invalid_gui
  | :missing_key

Reason returned in {:error, reason}.

key_type()

@type key_type() :: :cpf | :cnpj | :phone | :email | :evp

Pix key type, for the :key_type option of encode/1.

params()

@type params() :: %{
  :key => String.t(),
  :merchant_name => String.t(),
  :merchant_city => String.t(),
  optional(:key_type) => key_type(),
  optional(:amount) => pos_integer() | String.t(),
  optional(:txid) => String.t(),
  optional(:description) => String.t()
}

Parameters of encode/1.

Functions

decode(payload)

@spec decode(term()) :: {:ok, PixBrcode.Payload.t()} | {:error, error()}

Reads a Pix payload, checking CRC, structure and GUI.

The key is returned in the DICT canonical form, the same way encode/1 writes it ("123.456.789-09" becomes "12345678909"). Check digits are not verified here: the CRC already guarantees the payload was not corrupted.

iex> {:ok, payload} = PixBrcode.decode("00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D")
iex> {payload.type, payload.key, payload.merchant_name}
{:static, "123e4567-e12b-12d1-a456-426655440000", "Fulano de Tal"}

encode(params)

@spec encode(params()) :: {:ok, String.t()} | {:error, error()}

Builds a static Pix payload.

Required: :key, :merchant_name (max 25 chars), :merchant_city (max 15 chars). Optional: :amount ("10.50" or integer cents 1050), :txid (default "***"), :description, :key_type. Accents in name and city are removed.

The key may come formatted ("123.456.789-09", "+55 (11) 98765-4321", " Fulano@Exemplo.com ") and is written in the DICT canonical form. CPF and CNPJ (numeric or alphanumeric) must have valid check digits. An 11-digit number is read as a CPF; pass key_type: :phone for a phone number without +55.

iex> PixBrcode.encode(%{key: "123e4567-e12b-12d1-a456-426655440000",
...>   merchant_name: "Fulano de Tal", merchant_city: "BRASILIA"})
{:ok, "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D"}

encode_dynamic(params)

@spec encode_dynamic(dynamic_params()) :: {:ok, String.t()} | {:error, error()}

Builds a dynamic Pix payload, pointing to a URL provided by the receiver's bank.

Required: :url (without https://), :merchant_name, :merchant_city. Amount and txid live in the bank's server, not in the payload.

iex> {:ok, payload} = PixBrcode.encode_dynamic(%{url: "pix.example.com/qr/v2/abc",
...>   merchant_name: "Fulano de Tal", merchant_city: "BRASILIA"})
iex> PixBrcode.decode(payload) |> elem(1) |> Map.take([:type, :url])
%{type: :dynamic, url: "pix.example.com/qr/v2/abc"}

valid?(payload)

@spec valid?(term()) :: boolean()

Returns true if payload decodes successfully.

iex> PixBrcode.valid?("00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D")
true