bakong-khqr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58040c211ace06a112a68a19d0f74a3ab8e5ec932c86941b6b3e5c44b3b3aa0c
+  data.tar.gz: a5fb9615b8525c7b9ddc7c86ddb39b0e3eb014e0ea8a63f6127682282a3d0205
+SHA512:
+  metadata.gz: fcaf93cd86a3fe0b65defd14dbc4f0dce62b8216bcab6264a43875985b7b2494bd92bc8724773f494f6135c5d2543c3fde517fbdd608095f37c76020682c7f2b
+  data.tar.gz: 957b4cdf11f5206751feb7d6143fb492e55b50ac6da831e907ea09553590e0310cf64d78fd610f075aa4e6cdb2616c94fb6e71eb5fd8f7b2da9c6f3382ba973c

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to **bakong-khqr** will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-16
+
+### Added
+- Initial Ruby port of the official [bakong-khqr](https://www.npmjs.com/package/bakong-khqr) JavaScript SDK v1.0.20.
+- `Bakong::Khqr.generate_individual` and `.generate_merchant` for KHQR string + MD5 generation.
+- `Bakong::Khqr.decode` and `.decode_non_khqr` for parsing KHQR (and arbitrary EMVCo TLV) payloads.
+- `Bakong::Khqr.verify` for CRC-16/CCITT-FALSE checksum validation.
+- `Bakong::Khqr.check_bakong_account` and `.generate_deep_link` Bakong Open API clients (`Net::HTTP`, zero gem deps).
+- `Bakong::Khqr::IndividualInfo`, `MerchantInfo`, `SourceInfo`, and `CURRENCY` constants.
+- RSpec parity test suite ported from the upstream npm package's Jest fixtures.

data/LICENSE.txt

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Vandy Sodanheang
+
+This Ruby gem is a port of the bakong-khqr npm package by Devit Huotkeo
+(https://www.npmjs.com/package/bakong-khqr), originally licensed under ISC.
+All original copyright notices apply to the algorithms and data structures
+derived from that work.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# bakong-khqr
+
+[![Gem Version](https://badge.fury.io/rb/bakong-khqr.svg)](https://rubygems.org/gems/bakong-khqr)
+
+A Ruby SDK for **KHQR** — the centralized QR Code used by every mobile banking
+app in Cambodia. Generate, decode, and verify KHQR payloads, and talk to the
+Bakong Open API.
+
+This is a Ruby port of the official
+[`bakong-khqr`](https://www.npmjs.com/package/bakong-khqr) JavaScript SDK by
+Devit Huotkeo. The public API mirrors the npm package one-to-one; only the
+naming has been Ruby-fied (snake_case methods and hash keys). Zero runtime gem
+dependencies — uses only the Ruby standard library.
+
+> **KHQR ~ Scan. Pay. Done.**
+
+## Requirements
+
+- Ruby `>= 3.4.1`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "bakong-khqr"
+```
+
+Or install directly:
+
+```sh
+gem install bakong-khqr
+```
+
+Then require:
+
+```ruby
+require "bakong/khqr"
+```
+
+## Usage
+
+### Generate an Individual KHQR
+
+```ruby
+require "bakong/khqr"
+
+info = Bakong::Khqr::IndividualInfo.new(
+  bakong_account_id: "vandy@aclb",
+  merchant_name:     "Vandy Sodanheang",
+  merchant_city:     "Phnom Penh",
+  currency:          Bakong::Khqr::CURRENCY[:khr],
+  amount:            50_000,
+  bill_number:       "INV-2026-0001",
+  mobile_number:     "85512345678",
+  store_label:       "BKK-1",
+  terminal_label:    "Counter-1",
+  expiration_timestamp: (Time.now.to_f * 1000).to_i + 5 * 60 * 1000  # 5 min
+)
+
+result = Bakong::Khqr.generate_individual(info)
+result[:qr]   # → "00020101021229180014vandy@aclb52045999..."
+result[:md5]  # → MD5 digest of the QR string
+```
+
+For static QRs (no amount, no expiration), simply omit `:amount`.
+
+### Generate a Merchant KHQR
+
+```ruby
+info = Bakong::Khqr::MerchantInfo.new(
+  bakong_account_id: "vandy@aclb",
+  merchant_name:     "Sodanheang Coffee",
+  merchant_city:     "Phnom Penh",
+  merchant_id:       "1234567890",
+  acquiring_bank:    "ACLEDA Bank",
+  currency:          Bakong::Khqr::CURRENCY[:usd],
+  amount:            1.50,
+  expiration_timestamp: (Time.now.to_f * 1000).to_i + 5 * 60 * 1000
+)
+
+Bakong::Khqr.generate_merchant(info)
+# → { qr: "...", md5: "..." }
+```
+
+### Verify a KHQR
+
+```ruby
+Bakong::Khqr.verify(qr_string)  # → true | false
+```
+
+Returns `true` only when both the trailing CRC-16/CCITT-FALSE checksum and the
+per-tag validation pass.
+
+### Decode a KHQR
+
+```ruby
+decoded = Bakong::Khqr.decode(qr_string)
+# → {
+#     merchant_type: "29",
+#     bakong_account_id: "vandy@aclb",
+#     account_information: nil,
+#     payload_format_indicator: "01",
+#     point_of_initiation_method: "12",
+#     merchant_category_code: "5999",
+#     transaction_currency: "116",
+#     transaction_amount: "50000",
+#     country_code: "KH",
+#     merchant_name: "Vandy Sodanheang",
+#     merchant_city: "Phnom Penh",
+#     bill_number: "INV-2026-0001",
+#     mobile_number: "85512345678",
+#     store_label: "BKK-1",
+#     terminal_label: "Counter-1",
+#     purpose_of_transaction: nil,
+#     language_preference: nil,
+#     merchant_name_alternate_language: nil,
+#     merchant_city_alternate_language: nil,
+#     creation_timestamp: "1747...",
+#     expiration_timestamp: "1747...",
+#     crc: "A586"
+#   }
+```
+
+Use `Bakong::Khqr.decode_non_khqr(qr_string)` to decode arbitrary EMVCo TLV QRs
+(returns a string-keyed hash with up to three levels of nesting).
+
+### Check whether a Bakong account exists
+
+```ruby
+result = Bakong::Khqr.check_bakong_account(
+  "https://api-bakong.nbc.gov.kh/v1/check_bakong_account",
+  "vandy@aclb"
+)
+# → { bakong_account_existed: true }
+```
+
+### Generate a deep link
+
+```ruby
+source = Bakong::Khqr::SourceInfo.new(
+  app_icon_url:           "https://yourapp.example/icon.png",
+  app_name:               "Your App",
+  app_deep_link_callback: "yourapp://payment-result"
+)
+
+Bakong::Khqr.generate_deep_link(
+  "https://api-bakong.nbc.gov.kh/v1/generate_deeplink_by_qr",
+  qr_string,
+  source_info: source
+)
+# → { short_link: "https://bakong.link/abc123" }
+```
+
+`source_info` is optional; pass `nil` to skip it. When provided, all three
+fields are required.
+
+## Error handling
+
+All validation and transport errors raise `Bakong::Khqr::Error`, which carries
+the upstream numeric error code in `#code` and a human-readable `#message`:
+
+```ruby
+begin
+  Bakong::Khqr.generate_individual(info)
+rescue Bakong::Khqr::Error => e
+  puts "code=#{e.code} message=#{e.message}"
+end
+```
+
+Error codes (1–51) are kept identical to the upstream JavaScript SDK so that
+existing dashboards and i18n strings keyed off them continue to work. See
+[lib/bakong/khqr/error_codes.rb](lib/bakong/khqr/error_codes.rb) for the full
+list.
+
+## API mapping (npm → gem)
+
+| JavaScript                                       | Ruby                                                    |
+| ------------------------------------------------ | ------------------------------------------------------- |
+| `BakongKHQR.prototype.generateIndividual(info)`  | `Bakong::Khqr.generate_individual(info)`                |
+| `BakongKHQR.prototype.generateMerchant(info)`    | `Bakong::Khqr.generate_merchant(info)`                  |
+| `BakongKHQR.decode(qr)`                          | `Bakong::Khqr.decode(qr)`                               |
+| `BakongKHQR.decodeNonKhqr(qr)`                   | `Bakong::Khqr.decode_non_khqr(qr)`                      |
+| `BakongKHQR.verify(qr).isValid`                  | `Bakong::Khqr.verify(qr)`                               |
+| `BakongKHQR.checkBakongAccount(url, id)`         | `Bakong::Khqr.check_bakong_account(url, id)`            |
+| `BakongKHQR.generateDeepLink(url, qr, source)`   | `Bakong::Khqr.generate_deep_link(url, qr, source_info:)`|
+| `new IndividualInfo(id, name, city, optional)`   | `Bakong::Khqr::IndividualInfo.new(...)` (keyword args)  |
+| `new MerchantInfo(id, name, city, mid, ab, opt)` | `Bakong::Khqr::MerchantInfo.new(...)` (keyword args)    |
+| `new SourceInfo(icon, name, cb)`                 | `Bakong::Khqr::SourceInfo.new(...)` (keyword args)      |
+| `khqrData.currency.{khr,usd}`                    | `Bakong::Khqr::CURRENCY[:khr]`, `Bakong::Khqr::CURRENCY[:usd]` |
+
+## Development
+
+```sh
+bin/setup        # bundle install
+bundle exec rspec
+bundle exec rake # default task = spec
+```
+
+To open a console with the gem loaded:
+
+```sh
+bin/console
+```
+
+## Contributing
+
+Issues and pull requests are welcome at
+<https://github.com/VandyTheCoder/bakong-khqr-ruby>.
+
+## Credits
+
+- Upstream JavaScript SDK: [bakong-khqr](https://www.npmjs.com/package/bakong-khqr) by [Devit Huotkeo](https://github.com/davidhuotkeo).
+- KHQR specification: [National Bank of Cambodia](https://bakong.nbc.gov.kh/).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt). All algorithm and data-structure
+copyright from the upstream `bakong-khqr` npm package (ISC license) is
+preserved per its terms.

data/bakong-khqr.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/bakong/khqr/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "bakong-khqr"
+  spec.version       = Bakong::Khqr::VERSION
+  spec.authors       = ["Vandy Sodanheang"]
+  spec.email         = ["vandysodanheang@gmail.com"]
+
+  spec.summary       = "Ruby SDK for KHQR (Khmer QR Code) — generate, decode, and verify Bakong KHQR strings."
+  spec.description   = <<~DESC
+    A Ruby port of the official bakong-khqr JavaScript SDK
+    (https://www.npmjs.com/package/bakong-khqr) by Devit Huotkeo.
+
+    Generate Individual and Merchant KHQR payloads, decode existing KHQR strings,
+    verify the embedded CRC-16/CCITT-FALSE checksum, and call the Bakong Open API
+    to check accounts and produce deep links. Zero runtime gem dependencies — uses
+    only the Ruby standard library.
+  DESC
+  spec.homepage      = "https://github.com/VandyTheCoder/bakong-khqr-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.4.1"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["lib/**/*.rb", "*.md", "LICENSE.txt", "bakong-khqr.gemspec"]
+  end
+  spec.require_paths = ["lib"]
+  spec.bindir        = "exe"
+  spec.executables   = []
+end

data/lib/bakong/khqr/constants.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Bakong
+  module Khqr
+    CURRENCY = {
+      usd: 840,
+      khr: 116
+    }.freeze
+
+    MERCHANT_TYPE = {
+      merchant: "merchant",
+      individual: "individual"
+    }.freeze
+
+    EMV = {
+      PAYLOAD_FORMAT_INDICATOR: "00",
+      DEFAULT_PAYLOAD_FORMAT_INDICATOR: "01",
+      POINT_OF_INITIATION_METHOD: "01",
+      STATIC_QR: "11",
+      DYNAMIC_QR: "12",
+      MERCHANT_ACCOUNT_INFORMATION_INDIVIDUAL: "29",
+      MERCHANT_ACCOUNT_INFORMATION_MERCHANT: "30",
+      BAKONG_ACCOUNT_IDENTIFIER: "00",
+      MERCHANT_ACCOUNT_INFORMATION_MERCHANT_ID: "01",
+      INDIVIDUAL_ACCOUNT_INFORMATION: "01",
+      MERCHANT_ACCOUNT_INFORMATION_ACQUIRING_BANK: "02",
+      MERCHANT_CATEGORY_CODE: "52",
+      DEFAULT_MERCHANT_CATEGORY_CODE: "5999",
+      TRANSACTION_CURRENCY: "53",
+      TRANSACTION_AMOUNT: "54",
+      DEFAULT_TRANSACTION_AMOUNT: "0",
+      COUNTRY_CODE: "58",
+      DEFAULT_COUNTRY_CODE: "KH",
+      MERCHANT_NAME: "59",
+      MERCHANT_CITY: "60",
+      DEFAULT_MERCHANT_CITY: "Phnom Penh",
+      CRC: "63",
+      CRC_LENGTH: "04",
+      ADDITIONAL_DATA_TAG: "62",
+      BILLNUMBER_TAG: "01",
+      ADDITIONAL_DATA_FIELD_MOBILE_NUMBER: "02",
+      STORELABEL_TAG: "03",
+      TERMINAL_TAG: "07",
+      PURPOSE_OF_TRANSACTION: "08",
+      TIMESTAMP_TAG: "99",
+      CREATION_TIMESTAMP: "00",
+      EXPIRATION_TIMESTAMP: "01",
+      MERCHANT_INFORMATION_LANGUAGE_TEMPLATE: "64",
+      LANGUAGE_PREFERENCE: "00",
+      MERCHANT_NAME_ALTERNATE_LANGUAGE: "01",
+      MERCHANT_CITY_ALTERNATE_LANGUAGE: "02",
+      UNIONPAY_MERCHANT_ACCOUNT: "15",
+      INVALID_LENGTH: {
+        KHQR: 12,
+        MERCHANT_NAME: 25,
+        BAKONG_ACCOUNT: 32,
+        AMOUNT: 13,
+        COUNTRY_CODE: 3,
+        MERCHANT_CATEGORY_CODE: 4,
+        MERCHANT_CITY: 15,
+        TIMESTAMP: 13,
+        TRANSACTION_AMOUNT: 14,
+        TRANSACTION_CURRENCY: 3,
+        BILL_NUMBER: 25,
+        STORE_LABEL: 25,
+        TERMINAL_LABEL: 25,
+        PURPOSE_OF_TRANSACTION: 25,
+        MERCHANT_ID: 32,
+        ACQUIRING_BANK: 32,
+        MOBILE_NUMBER: 25,
+        ACCOUNT_INFORMATION: 32,
+        MERCHANT_INFORMATION_LANGUAGE_TEMPLATE: 99,
+        UPI_MERCHANT: 99,
+        LANGUAGE_PREFERENCE: 2,
+        MERCHANT_NAME_ALTERNATE_LANGUAGE: 25,
+        MERCHANT_CITY_ALTERNATE_LANGUAGE: 15
+      }.freeze
+    }.freeze
+  end
+end

data/lib/bakong/khqr/controllers/decode.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "../khqr_tag"
+require_relative "../khqr_subtag"
+require_relative "../helpers/cut_string"
+
+module Bakong
+  module Khqr
+    module Controllers
+      # Parses a KHQR string into a snake_case symbol-keyed Hash. Tag 30
+      # (merchant) is normalized to tag 29 in the output so downstream
+      # consumers only need to handle one merchant_type discriminator.
+      module Decode
+        module_function
+
+        def call(khqr_string)
+          all_fields = KHQR_TAG.map { |el| el[:tag] }
+          subtag_set = KHQR_TAG.select { |el| el[:sub] }.map { |el| el[:tag] }
+          sub_tag_input = KHQR_SUBTAG[:input]
+          sub_tag_compare = KHQR_SUBTAG[:compare]
+
+          tags = {}
+          merchant_type = nil
+          last_tag = ""
+          is_merchant_tag = false
+          remainder = khqr_string
+
+          until remainder.nil? || remainder.empty?
+            slice = Helpers::CutString.call(remainder)
+            tag = slice[:tag]
+            value = slice[:value]
+            remainder = slice[:remainder]
+
+            break if tag == last_tag
+
+            if tag == "30"
+              merchant_type = "30"
+              tag = "29"
+              is_merchant_tag = true
+            elsif tag == "29"
+              merchant_type = "29"
+            end
+
+            tags[tag] = value if all_fields.include?(tag)
+            last_tag = tag
+          end
+
+          decode_value = { merchant_type: merchant_type }
+          sub_tag_input.each { |el| decode_value.merge!(el[:data]) }
+
+          KHQR_TAG.each do |khqr_tag|
+            tag = khqr_tag[:tag]
+            value = tags[tag]
+            input_value = value
+
+            if subtag_set.include?(tag)
+              schema = sub_tag_input.find { |el| el[:tag] == tag }[:data]
+              input_data = deep_dup(schema)
+
+              while value && !value.empty?
+                cut = Helpers::CutString.call(value)
+                sub_tag = cut[:tag]
+                sub_value = cut[:value]
+                value = cut[:remainder]
+
+                name_subtag = sub_tag_compare
+                              .select { |el| el[:tag] == tag }
+                              .find { |el| el[:sub_tag] == sub_tag }
+
+                next unless name_subtag
+
+                name = name_subtag[:name]
+                name = :merchant_id if is_merchant_tag && name == :account_information
+                input_data[name] = sub_value
+                input_value = input_data
+              end
+
+              decode_value.merge!(input_value) if input_value.is_a?(Hash)
+            else
+              decode_value[khqr_tag[:type]] = value
+            end
+          end
+
+          decode_value
+        end
+
+        def deep_dup(hash)
+          hash.each_with_object({}) { |(k, v), acc| acc[k] = v.is_a?(Hash) ? deep_dup(v) : v }
+        end
+      end
+    end
+  end
+end

data/lib/bakong/khqr/controllers/decode_non_khqr.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Bakong
+  module Khqr
+    module Controllers
+      # Generic EMVCo TLV decoder for QR strings that may or may not be KHQR.
+      # Walks up to three levels of nested TLV for the same composite-tag
+      # ranges the upstream JS package handles (26–51, 80–99, 62, 64).
+      module DecodeNonKHQR
+        module_function
+
+        def call(qr)
+          first_level = {}
+          final_data = {}
+          remainder = qr
+
+          loop do
+            parsed = extract_tlv(remainder)
+            break unless valid?(parsed[:tag], parsed[:length], parsed[:value])
+
+            first_level[parsed[:tag]] = parsed[:value]
+            remainder = parsed[:remain]
+            break if remainder.nil? || remainder.empty?
+          end
+
+          first_level.each do |tag, value|
+            final_data[tag] = value
+            next unless composite_tag?(tag)
+            next if value.length < 6
+
+            second_level = {}
+            remaining_value = value
+
+            loop do
+              third_level = {}
+              parsed = extract_tlv(remaining_value)
+              break unless valid?(parsed[:tag], parsed[:length], parsed[:value])
+
+              sub_tag = parsed[:tag]
+              sub_value = parsed[:value]
+              remaining_value = parsed[:remain]
+
+              if tag == "62" && (50..99).cover?(sub_tag.to_i)
+                inner = sub_value
+                loop do
+                  inner_parsed = extract_tlv(inner)
+                  break unless valid?(inner_parsed[:tag], inner_parsed[:length], inner_parsed[:value])
+
+                  third_level[inner_parsed[:tag]] = inner_parsed[:value]
+                  inner = inner_parsed[:remain]
+                  break if inner.nil? || inner.empty?
+                end
+              end
+
+              second_level[sub_tag] = third_level.empty? ? sub_value : third_level
+              break if remaining_value.nil? || remaining_value.empty?
+            end
+
+            final_data[tag] = second_level unless second_level.empty?
+          end
+
+          final_data
+        end
+
+        def extract_tlv(string)
+          tag = string[0, 2].to_s
+          length = string[2, 2].to_i
+          value = string[4, length].to_s
+          remain = string[(4 + length)..] || ""
+          { tag: tag, length: length, value: value, remain: remain }
+        end
+
+        def composite_tag?(tag)
+          int = tag.to_i
+          (26..51).cover?(int) || (80..99).cover?(int) || tag == "64" || tag == "62"
+        end
+
+        def valid?(tag, length, value)
+          tag.match?(/\A\d+\z/) && length == value.length
+        end
+      end
+    end
+  end
+end

data/lib/bakong/khqr/controllers/decode_validation.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "../error"
+require_relative "../error_codes"
+require_relative "../khqr_tag"
+require_relative "../khqr_subtag"
+require_relative "../helpers/cut_string"
+
+module Bakong
+  module Khqr
+    module Controllers
+      # Walks a candidate KHQR string TLV-by-TLV, instantiating each tag's
+      # validator class. Used by `verify` after the CRC check passes.
+      module DecodeValidation
+        module_function
+
+        def call(khqr_string)
+          all_fields = KHQR_TAG.map { |el| el[:tag] }
+          subtag_set = KHQR_TAG.select { |el| el[:sub] }.map { |el| el[:tag] }
+          required_fields = KHQR_TAG.select { |el| el[:required] }.map { |el| el[:tag] }
+          sub_tag_input = KHQR_SUBTAG[:input]
+          sub_tag_compare = KHQR_SUBTAG[:compare]
+
+          tags = []
+          merchant_type = "individual"
+          last_tag = ""
+          remainder = khqr_string
+
+          until remainder.nil? || remainder.empty?
+            slice = Helpers::CutString.call(remainder)
+            tag = slice[:tag]
+            value = slice[:value]
+            remainder = slice[:remainder]
+
+            break if tag == last_tag
+
+            if tag == "30"
+              merchant_type = "merchant"
+              tag = "29"
+            end
+
+            if all_fields.include?(tag)
+              tags << { tag: tag, value: value }
+              required_fields.delete(tag)
+            end
+
+            last_tag = tag
+          end
+
+          if tags.any? { |t| t[:tag] == "01" && t[:value] == "12" }
+            raise Error.from(ERROR_CODES[:INVALID_DYNAMIC_KHQR]) unless tags.any? { |t| t[:tag] == "54" }
+            raise Error.from(ERROR_CODES[:EXPIRATION_TIMESTAMP_REQUIRED]) unless tags.any? { |t| t[:tag] == "99" }
+          end
+
+          if tags.any? { |t| t[:tag] == "54" } && tags.none? { |t| t[:tag] == "99" }
+            raise Error.from(ERROR_CODES[:EXPIRATION_TIMESTAMP_REQUIRED])
+          end
+
+          unless required_fields.empty?
+            required_tag = required_fields.first
+            missing_instance = KHQR_TAG.find { |el| el[:tag] == required_tag }[:instance]
+            missing_instance.new(required_tag, nil) # raises with the proper error
+          end
+
+          decode_value = { merchant_type: merchant_type }
+          sub_tag_input.each { |el| decode_value.merge!(el[:data]) }
+
+          poi = nil
+          tags.each do |khqr_tag|
+            tag = khqr_tag[:tag]
+            schema = KHQR_TAG.find { |el| el[:tag] == tag }
+            value = khqr_tag[:value]
+            input_value = value
+            poi = value if tag == EMV[:POINT_OF_INITIATION_METHOD]
+
+            if subtag_set.include?(tag)
+              input_data_template = sub_tag_input.find { |el| el[:tag] == tag }[:data]
+              input_data = deep_dup(input_data_template)
+
+              while value && !value.empty?
+                cut = Helpers::CutString.call(value)
+                sub_tag = cut[:tag]
+                sub_value = cut[:value]
+                value = cut[:remainder]
+
+                name_subtag = sub_tag_compare
+                              .select { |el| el[:tag] == tag }
+                              .find { |el| el[:sub_tag] == sub_tag }
+
+                next unless name_subtag
+
+                input_data[name_subtag[:name]] = sub_value
+                input_value = input_data
+              end
+
+              decode_value.merge!(input_value) if input_value.is_a?(Hash)
+
+              if tag == EMV[:TIMESTAMP_TAG]
+                schema[:instance].new(tag, input_value, poi)
+              else
+                schema[:instance].new(tag, input_value)
+              end
+            else
+              instance = schema[:instance].new(tag, input_value)
+              decode_value[schema[:type]] = instance.value
+            end
+          end
+
+          decode_value
+        end
+
+        def deep_dup(hash)
+          hash.each_with_object({}) { |(k, v), acc| acc[k] = v.is_a?(Hash) ? deep_dup(v) : v }
+        end
+      end
+    end
+  end
+end