QRCode Pix Ruby

Ruby gem for Qrcode generation of Pix (Pagamento Instantâneo Brasileiro - Banco Central do Brasil).

Installation

Add this line to your application's Gemfile:

gem 'qrcode_pix_ruby'

And then execute:

bundle install

Or install it yourself as:

gem install qrcode_pix_ruby

Usage (examples)

Available parameters

pix_key/url
repeatable
currency
country_code
description
postal_code
merchant_name
merchant_city
transaction_id
amount

Static QR Code

require 'qrcode_pix_ruby'

pix = QrcodePixRuby::Payload.new(
  pix_key:        'minhachavedopix',
  description:    'Pagamento do pedido 123456',
  merchant_name:  'Fulano de Tal',
  merchant_city:  'SAO PAULO',
  transaction_id: 'TID12345',
  amount:         '100.00',
  currency:       '986',
  country_code:   'BR',
  postal_code:    '01131010',
  repeatable:     false
)

# If needed, change the attributes value later
pix.pix_key = 'minhaoutrachavepix'
pix.merchant_city = 'BRASILIA'

# QRCode copia-e-cola
puts pix.payload

# QRCode for images
puts pix.base64

Dynamic QR Code

require 'qrcode_pix_ruby'

pix = QrcodePixRuby::Payload.new(
  url:            'https://example.com',
  merchant_name:  'Fulano de Tal',
  merchant_city:  'SAO PAULO',
  amount:         '100.00',
  transaction_id: 'TID12345',
  repeatable:     false
)

# If needed, change the attributes value later
pix.url = 'https://another-example.com'
pix.amount = 1.50

# QRCode copia-e-cola
puts pix.payload

# QRCode para uso em imagens
puts pix.base64

🚨 Important note: BACEN (Banco Central do Brasil) sets a variety of rules for each field in QRCode Payload (maximum number of characters, invalid values, mandatory and optional fields, and so on). So, pay attention that a QRCode payload+base64 generated by the gem can be valid, theorically, but may not be accepted in banking apps because of these restrictions (that are out of scope of gem).

Execute tests/specs locally

To execute gem tests locally, use Docker with the commands below:

git clone https://github.com/pedrofurtado/qrcode_pix_ruby
cd qrcode_pix_ruby/
docker build -t qrcode_pix_ruby_specs .

# Then, run this command how many times you want,
# after editing local files, and so on, to get
# feedback from test suite of gem.
docker run -v $(pwd):/app/ -it qrcode_pix_ruby_specs

Execute demo locally

To execute demo locally, use Docker with the commands below:

git clone https://github.com/pedrofurtado/qrcode_pix_ruby
cd qrcode_pix_ruby/demo/
docker build -t qrcode_pix_ruby_demo .

# Then, access http://localhost:3000 the see demo in action.
docker run -p 3000:3000 -it qrcode_pix_ruby_demo

Useful links

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/pedrofurtado/qrcode_pix_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the qrcode_pix_ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

qrcode_pix_ruby

Development

Runtime