pix_emv_decoder_ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85887cdd738b61284476793491f3a188a38b408d1db3b4c62bdaba62632a3f16
+  data.tar.gz: 705f5c9be06f601297fbb85ae0cdec6c97a83a712aad1adcb8d97a6e1b37f047
+SHA512:
+  metadata.gz: 873a9e1c87e5c68e83ebe0e97fa492b6e1c36668dd690b209144e5565fc7224e1f262f50d5b3d3c8077046cee87dfef8fa806e30653d3f9d707735e0e888db71
+  data.tar.gz: d73363330d7f6ace9450ecd422b8101fac463e8bdaf24b722155a1cbe91c21e83883e627f6ac5dc29bf0b26f0a80547c6d9ade63b867b72e30139de42c8defed

data/README.md

@@ -0,0 +1,127 @@
+# PixEmvDecoderRuby
+
+[![Gem Version](https://badge.fury.io/rb/pix_emv_decoder_ruby.svg)](https://rubygems.org/gems/pix_emv_decoder_ruby)
+
+A simple Ruby library for decoding **PIX EMV QR Codes** (both static and dynamic).
+It parses the `copia e cola` string into a Ruby hash with meaningful keys like merchant name, PIX key, transaction amount, etc.
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "pix_emv_decoder_ruby"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install pix_emv_decoder_ruby
+```
+
+---
+
+## Usage
+
+Require the gem:
+
+```ruby
+require "pix_emv_decoder_ruby"
+```
+
+Decode a PIX EMV payload:
+
+```ruby
+payload = "00020126550014br.gov.bcb.pix0117wgirhad@gmail.com0212awesome test5204000053039865406420.695802BR5914Willian Girhad6009Sao Paulo622805247aec6590a492461a8bb140fe630445CE"
+
+decoded = PixEmvDecoderRuby.decode(payload)
+
+puts decoded
+# {
+#   payload_format_indicator: "01",
+#   merchant_account_information: {
+#     globally_unique_identifier: "br.gov.bcb.pix",
+#     chave_pix: "wgirhad@gmail.com",
+#     informacoes_adicionais: "awesome test"
+#   },
+#   merchant_category_code: "0000",
+#   transaction_currency: :brl,
+#   transaction_amount: BigDecimal("420.69"),
+#   country_code: "BR",
+#   merchant_name: "Willian Girhad",
+#   merchant_city: "Sao Paulo",
+#   additional_data_field_template: {
+#     reference_label: "7aec6590a492461a8bb140fe"
+#   },
+#   crc: "45CE"
+# }
+```
+
+### Dynamic QR Code Example
+
+```ruby
+payload = "00020126660014br.gov.bcb.pix2544coolbank.net/pix/v1/7aec6590a492461a8bb140fe5204000053039865802BR5903PIX6009Sao Paulo62070503***63041D24"
+
+decoded = PixEmvDecoderRuby.decode(payload)
+
+puts decoded
+# {
+#   payload_format_indicator: "01",
+#   merchant_account_information: {
+#     globally_unique_identifier: "br.gov.bcb.pix",
+#     url: "coolbank.net/pix/v1/7aec6590a492461a8bb140fe"
+#   },
+#   merchant_category_code: "0000",
+#   transaction_currency: :brl,
+#   country_code: "BR",
+#   merchant_name: "PIX",
+#   merchant_city: "Sao Paulo",
+#   additional_data_field_template: {
+#     reference_label: "***"
+#   },
+#   crc: "1D24"
+# }
+```
+
+---
+
+## Features
+
+- ✅ Supports **Static** and **Dynamic** PIX QR Codes
+- ✅ Returns a clean, Ruby-style hash
+- ✅ Parses `transaction_amount` as `BigDecimal` when available
+- ✅ Provides merchant info, PIX key/URL, CRC, and more
+
+---
+
+## Development
+
+Clone the repository and run the tests:
+
+```bash
+git clone https://github.com/wgirhad/pix_emv_decoder_ruby.git
+cd pix_emv_decoder_ruby
+bundle install
+bundle exec rspec
+```
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/wgirhad/pix_emv_decoder_ruby).
+This project is intended to be a safe, welcoming space for collaboration.
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/pix_emv_decoder_ruby/decoder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  class Decoder
+    def decode(emv, base: '')
+      result = {}
+      pointer = 0
+
+      loop do
+        pointer, key, value = pick_next(pointer, emv, base)
+
+        break if key.nil?
+
+        result[key] = value
+      end
+
+      result
+    end
+
+    private
+
+    def pick_next(pointer, emv, base)
+      rest = emv[pointer..]
+
+      return nil if rest.empty?
+
+      key = rest[0...2]
+      length = rest[2...4].to_i
+      rest = rest[4...]
+      value = rest[0...length]
+      pointer = pointer + length + 4
+      type_key = "#{base}#{key}"
+
+      result = Types.fetch(type_key).new(type_key, value)
+
+      [pointer, result.key, result.value]
+    end
+  end
+end

data/lib/pix_emv_decoder_ruby/types/additional_data_field_template.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class AdditionalDataFieldTemplate < Hash
+      def key
+        :additional_data_field_template
+      end
+
+      def self.key_code
+        '62'
+      end
+    end
+
+    register AdditionalDataFieldTemplate
+  end
+end

data/lib/pix_emv_decoder_ruby/types/country_code.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class CountryCode < String
+      def key
+        :country_code
+      end
+
+      def self.key_code
+        '58'
+      end
+    end
+
+    register CountryCode
+  end
+end

data/lib/pix_emv_decoder_ruby/types/crc.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class Crc < String
+      def key
+        :crc
+      end
+
+      def self.key_code
+        '63'
+      end
+    end
+
+    register Crc
+  end
+end

data/lib/pix_emv_decoder_ruby/types/decimal.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module PixEmvDecoderRuby
+  module Types
+    class Decimal < Type
+      def value
+        @value ||= BigDecimal(@raw_value)
+      end
+    end
+  end
+end

data/lib/pix_emv_decoder_ruby/types/hash.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class Hash < Type
+      def value
+        @value ||= PixEmvDecoderRuby.decode(@raw_value, base: @raw_key)
+      end
+    end
+  end
+end

data/lib/pix_emv_decoder_ruby/types/merchant_account_information.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class MerchantAccountInformation < Hash
+      def key
+        :merchant_account_information
+      end
+
+      def value
+        @value ||= PixEmvDecoderRuby.decode(@raw_value, base:)
+      end
+
+      def self.key_code
+        '26'
+      end
+
+      private
+
+      def base
+        case @raw_value
+        when /^0014br.gov.bcb.pix/i then 'pix'
+        else @raw_key
+        end
+      end
+    end
+
+    register MerchantAccountInformation
+  end
+end

data/lib/pix_emv_decoder_ruby/types/merchant_category_code.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class MerchantCategoryCode < String
+      def key
+        :merchant_category_code
+      end
+
+      def self.key_code
+        '52'
+      end
+    end
+
+    register MerchantCategoryCode
+  end
+end

data/lib/pix_emv_decoder_ruby/types/merchant_city.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class MerchantCity < String
+      def key
+        :merchant_city
+      end
+
+      def self.key_code
+        '60'
+      end
+    end
+
+    register MerchantCity
+  end
+end

data/lib/pix_emv_decoder_ruby/types/merchant_name.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class MerchantName < String
+      def key
+        :merchant_name
+      end
+
+      def self.key_code
+        '59'
+      end
+    end
+
+    register MerchantName
+  end
+end

data/lib/pix_emv_decoder_ruby/types/payload_format_indicator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class PayloadFormatIndicator < String
+      def key
+        :payload_format_indicator
+      end
+
+      def self.key_code
+        '00'
+      end
+    end
+
+    register PayloadFormatIndicator
+  end
+end

data/lib/pix_emv_decoder_ruby/types/pix/chave_pix.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../string'
+
+module PixEmvDecoderRuby
+  module Types
+    module Pix
+      class ChavePix < Types::String
+        def key
+          :chave_pix
+        end
+
+        def self.key_code
+          'pix01'
+        end
+      end
+    end
+
+    register Pix::ChavePix
+  end
+end

data/lib/pix_emv_decoder_ruby/types/pix/globally_unique_identifier.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../string'
+
+module PixEmvDecoderRuby
+  module Types
+    module Pix
+      class GloballyUniqueIdentifier < Types::String
+        def key
+          :globally_unique_identifier
+        end
+
+        def self.key_code
+          'pix00'
+        end
+      end
+    end
+
+    register Pix::GloballyUniqueIdentifier
+  end
+end

data/lib/pix_emv_decoder_ruby/types/pix/informacoes_adicionais.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../string'
+
+module PixEmvDecoderRuby
+  module Types
+    module Pix
+      class InformacoesAdicionais < Types::String
+        def key
+          :informacoes_adicionais
+        end
+
+        def self.key_code
+          'pix02'
+        end
+      end
+    end
+
+    register Pix::InformacoesAdicionais
+  end
+end

data/lib/pix_emv_decoder_ruby/types/pix/url.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../string'
+
+module PixEmvDecoderRuby
+  module Types
+    module Pix
+      class Url < Types::String
+        def key
+          :url
+        end
+
+        def self.key_code
+          'pix25'
+        end
+      end
+    end
+
+    register Pix::Url
+  end
+end

data/lib/pix_emv_decoder_ruby/types/point_of_initial_method.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class PointOfInitialMethod < String
+      def key
+        :point_of_initial_method
+      end
+
+      def self.key_code
+        '01'
+      end
+    end
+
+    register PointOfInitialMethod
+  end
+end

data/lib/pix_emv_decoder_ruby/types/reference_label.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class ReferenceLabel < String
+      def key
+        :reference_label
+      end
+
+      def self.key_code
+        '6205'
+      end
+    end
+
+    register ReferenceLabel
+  end
+end

data/lib/pix_emv_decoder_ruby/types/string.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class String < Type
+    end
+  end
+end

data/lib/pix_emv_decoder_ruby/types/transaction_amount.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class TransactionAmount < Decimal
+      def key
+        :transaction_amount
+      end
+
+      def self.key_code
+        '54'
+      end
+    end
+
+    register TransactionAmount
+  end
+end

data/lib/pix_emv_decoder_ruby/types/transaction_currency.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class TransactionCurrency < String
+      def key
+        :transaction_currency
+      end
+
+      def self.key_code
+        '53'
+      end
+
+      def value
+        { '008' => :all,
+          '012' => :dzd,
+          '032' => :ars,
+          '036' => :aud,
+          '044' => :bsd,
+          '048' => :bhd,
+          '050' => :bdt,
+          '051' => :amd,
+          '052' => :bbd,
+          '060' => :bmd,
+          '064' => :btn,
+          '068' => :bob,
+          '072' => :bwp,
+          '084' => :bzd,
+          '090' => :sbd,
+          '096' => :bnd,
+          '104' => :mmk,
+          '108' => :bif,
+          '116' => :khr,
+          '124' => :cad,
+          '132' => :cve,
+          '136' => :kyd,
+          '144' => :lkr,
+          '152' => :clp,
+          '156' => :cny,
+          '170' => :cop,
+          '174' => :kmf,
+          '188' => :crc,
+          '191' => :hrk,
+          '192' => :cup,
+          '203' => :czk,
+          '208' => :dkk,
+          '214' => :dop,
+          '222' => :svc,
+          '230' => :etb,
+          '232' => :ern,
+          '238' => :fkp,
+          '242' => :fjd,
+          '262' => :djf,
+          '270' => :gmd,
+          '292' => :gip,
+          '320' => :gtq,
+          '324' => :gnf,
+          '328' => :gyd,
+          '332' => :htg,
+          '340' => :hnl,
+          '344' => :hkd,
+          '348' => :huf,
+          '352' => :isk,
+          '356' => :inr,
+          '360' => :idr,
+          '364' => :irr,
+          '368' => :iqd,
+          '376' => :ils,
+          '388' => :jmd,
+          '392' => :jpy,
+          '396' => :xad,
+          '398' => :kzt,
+          '400' => :jod,
+          '404' => :kes,
+          '408' => :kpw,
+          '410' => :krw,
+          '414' => :kwd,
+          '417' => :kgs,
+          '418' => :lak,
+          '422' => :lbp,
+          '426' => :lsl,
+          '430' => :lrd,
+          '434' => :lyd,
+          '446' => :mop,
+          '454' => :mwk,
+          '458' => :myr,
+          '462' => :mvr,
+          '480' => :mur,
+          '484' => :mxn,
+          '496' => :mnt,
+          '498' => :mdl,
+          '504' => :mad,
+          '512' => :omr,
+          '516' => :nad,
+          '524' => :npr,
+          '532' => :ang,
+          '533' => :awg,
+          '548' => :vuv,
+          '554' => :nzd,
+          '558' => :nio,
+          '566' => :ngn,
+          '578' => :nok,
+          '586' => :pkr,
+          '590' => :pab,
+          '598' => :pgk,
+          '600' => :pyg,
+          '604' => :pen,
+          '608' => :php,
+          '634' => :qar,
+          '643' => :rub,
+          '646' => :rwf,
+          '654' => :shp,
+          '682' => :sar,
+          '690' => :scr,
+          '694' => :sll,
+          '702' => :sgd,
+          '704' => :vnd,
+          '706' => :sos,
+          '710' => :zar,
+          '728' => :ssp,
+          '748' => :szl,
+          '752' => :sek,
+          '756' => :chf,
+          '760' => :syp,
+          '764' => :thb,
+          '776' => :top,
+          '780' => :ttd,
+          '784' => :aed,
+          '788' => :tnd,
+          '800' => :ugx,
+          '807' => :mkd,
+          '818' => :egp,
+          '826' => :gbp,
+          '834' => :tzs,
+          '840' => :usd,
+          '858' => :uyu,
+          '860' => :uzs,
+          '882' => :wst,
+          '886' => :yer,
+          '901' => :twd,
+          '924' => :zwg,
+          '925' => :sle,
+          '926' => :ved,
+          '927' => :uyw,
+          '928' => :ves,
+          '929' => :mru,
+          '930' => :stn,
+          '931' => :cuc,
+          '932' => :zwl,
+          '933' => :byn,
+          '934' => :tmt,
+          '936' => :ghs,
+          '938' => :sdg,
+          '940' => :uyi,
+          '941' => :rsd,
+          '943' => :mzn,
+          '944' => :azn,
+          '946' => :ron,
+          '947' => :che,
+          '948' => :chw,
+          '949' => :try,
+          '950' => :xaf,
+          '951' => :xcd,
+          '952' => :xof,
+          '953' => :xpf,
+          '955' => :xba,
+          '956' => :xbb,
+          '957' => :xbc,
+          '958' => :xbd,
+          '959' => :xau,
+          '960' => :xdr,
+          '961' => :xag,
+          '962' => :xpt,
+          '963' => :xts,
+          '964' => :xpd,
+          '965' => :xua,
+          '967' => :zmw,
+          '968' => :srd,
+          '969' => :mga,
+          '970' => :cou,
+          '971' => :afn,
+          '972' => :tjs,
+          '973' => :aoa,
+          '975' => :bgn,
+          '976' => :cdf,
+          '977' => :bam,
+          '978' => :eur,
+          '979' => :mxv,
+          '980' => :uah,
+          '981' => :gel,
+          '984' => :bov,
+          '985' => :pln,
+          '986' => :brl,
+          '990' => :clf,
+          '994' => :xsu,
+          '997' => :usn,
+          '999' => :xxx }.fetch(@raw_value, @raw_value)
+      end
+    end
+
+    register TransactionCurrency
+  end
+end

data/lib/pix_emv_decoder_ruby/types/type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PixEmvDecoderRuby
+  module Types
+    class Type
+      def initialize(raw_key, raw_value)
+        @raw_key = raw_key
+        @raw_value = raw_value
+      end
+
+      def key
+        @raw_key
+      end
+
+      def value
+        @raw_value
+      end
+    end
+  end
+end

data/lib/pix_emv_decoder_ruby/types.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'types/type'
+require_relative 'types/string'
+require_relative 'types/hash'
+require_relative 'types/decimal'
+
+module PixEmvDecoderRuby
+  module Types
+    module_function
+
+    def fetch(key)
+      types.fetch(key, Types::String)
+    end
+
+    def register(type)
+      types[type.key_code] = type
+    end
+
+    def types
+      @types ||= {}
+    end
+  end
+end

data/lib/pix_emv_decoder_ruby.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'pix_emv_decoder_ruby/types'
+require_relative 'pix_emv_decoder_ruby/decoder'
+
+Dir.glob("#{__dir__}/pix_emv_decoder_ruby/types/**/*.rb").each do |file|
+  require file
+end
+
+module PixEmvDecoderRuby
+  module_function
+
+  def decode(...)
+    Decoder.new.decode(...)
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: pix_emv_decoder_ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Willian Girhad
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-02 00:00:00.000000000 Z
+dependencies: []
+description: Enables decoding emv strings from pix (copia e cola)
+email: wgirhad@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/pix_emv_decoder_ruby.rb
+- lib/pix_emv_decoder_ruby/decoder.rb
+- lib/pix_emv_decoder_ruby/types.rb
+- lib/pix_emv_decoder_ruby/types/additional_data_field_template.rb
+- lib/pix_emv_decoder_ruby/types/country_code.rb
+- lib/pix_emv_decoder_ruby/types/crc.rb
+- lib/pix_emv_decoder_ruby/types/decimal.rb
+- lib/pix_emv_decoder_ruby/types/hash.rb
+- lib/pix_emv_decoder_ruby/types/merchant_account_information.rb
+- lib/pix_emv_decoder_ruby/types/merchant_category_code.rb
+- lib/pix_emv_decoder_ruby/types/merchant_city.rb
+- lib/pix_emv_decoder_ruby/types/merchant_name.rb
+- lib/pix_emv_decoder_ruby/types/payload_format_indicator.rb
+- lib/pix_emv_decoder_ruby/types/pix/chave_pix.rb
+- lib/pix_emv_decoder_ruby/types/pix/globally_unique_identifier.rb
+- lib/pix_emv_decoder_ruby/types/pix/informacoes_adicionais.rb
+- lib/pix_emv_decoder_ruby/types/pix/url.rb
+- lib/pix_emv_decoder_ruby/types/point_of_initial_method.rb
+- lib/pix_emv_decoder_ruby/types/reference_label.rb
+- lib/pix_emv_decoder_ruby/types/string.rb
+- lib/pix_emv_decoder_ruby/types/transaction_amount.rb
+- lib/pix_emv_decoder_ruby/types/transaction_currency.rb
+- lib/pix_emv_decoder_ruby/types/type.rb
+homepage: https://rubygems.org/gems/pix_emv_decoder_ruby
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Decodes pix emv strings
+test_files: []