tingee_ruby_sdk 0.3.0

data/lib/tingee/error.rb

@@ -0,0 +1,14 @@
+module Tingee
+  # A non-"00" Tingee response, or a transport/config failure. `code` keeps Tingee's
+  # raw code for programmatic handling. Two undocumented-but-observed series exist and
+  # are NOT reconciled by Tingee: business codes 1001–1076, and signature codes
+  # 90 (bad timestamp) / 91 (timeout) / 97 (bad signature). We keep the raw code as-is.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(code, detail)
+      @code = code
+      super("Tingee error #{code}: #{detail}")
+    end
+  end
+end

data/lib/tingee/signature.rb

@@ -0,0 +1,44 @@
+require "openssl"
+require "json"
+
+module Tingee
+  # HMAC-SHA512 signing, per the official tingee-node SDK and verified live
+  # (docs/tingee-api-reference.md §Auth). Outbound requests sign
+  # `timestamp + ":" + minified_body`, where a bodyless request signs "{}" (not "")
+  # — signing "" returns code 97. Inbound webhooks are verified over the RAW body
+  # bytes, not a re-serialization (see #verify).
+  module Signature
+    module_function
+
+    # yyyyMMddHHmmssSSS in UTC+7. Server rejects >10 min clock drift (error 90).
+    def timestamp(now = Time.now)
+      now.getlocal("+07:00").strftime("%Y%m%d%H%M%S%L")
+    end
+
+    def generate(secret:, timestamp:, body:)
+      # `.b`: hash raw bytes (silences the json 3.0 UTF-8/BINARY warning); the
+      # digest of ASCII/UTF-8 bytes is unchanged either way.
+      OpenSSL::HMAC.hexdigest("SHA512", secret, "#{timestamp}:#{body}".b)
+    end
+
+    # Verify an inbound webhook signature. Resolved against a real captured payment
+    # webhook (2026-07-16): Tingee signs the RAW body bytes exactly as sent.
+    # We hash `raw_body` verbatim — do NOT re-parse/re-serialize. Raw is both correct
+    # and immune to Ruby-vs-JS number formatting (a re-serialized whole-number float
+    # would render "250000.0" in Ruby vs "250000" in JS and break a valid signature).
+    # The caller must pass the body exactly as received (Rails: `request.raw_post`),
+    # never a re-encoded body.
+    def verify(secret:, timestamp:, raw_body:, signature:)
+      secure_compare(generate(secret:, timestamp:, body: raw_body), signature.to_s)
+    end
+
+    # Constant-time comparison, hand-rolled so the gem needs no ActiveSupport.
+    def secure_compare(left, right)
+      return false unless left.bytesize == right.bytesize
+
+      diff = 0
+      left.each_byte.with_index { |byte, i| diff |= byte ^ right.getbyte(i) }
+      diff.zero?
+    end
+  end
+end

data/lib/tingee/version.rb

@@ -0,0 +1,3 @@
+module Tingee
+  VERSION = "0.3.0"
+end

data/lib/tingee/viet_qr.rb

@@ -0,0 +1,125 @@
+module Tingee
+  # VietQR payment payloads, built locally — no img.vietqr.io round-trip and no Tingee
+  # endpoint (theirs 500s, see docs/tingee-api-reference.md §10). A plain transfer into
+  # the linked real account fires the payment webhook whatever minted the QR, so the
+  # payer-facing code is purely a client-side string.
+  #
+  # Ported from https://github.com/openhoangnc/vietqr (MIT); test/tingee/viet_qr_test.rb
+  # reproduces that project's fixtures byte-exact.
+  #
+  # Returns the EMVCo payload STRING, not an image. QR pixel encoding is Reed-Solomon +
+  # masking, which would mean a runtime dependency and this gem has none — render the
+  # string app-side with rqrcode (Ruby) or any JS QR library.
+  module VietQR
+    # EMVCo tag 62-08 (purpose of transaction) caps at 25 characters.
+    MAX_DESCRIPTION = 25
+
+    NAPAS_AID    = "A000000727".freeze # merchant account information: Napas
+    SERVICE_CODE = "QRIBFTTA".freeze   # interbank funds transfer TO AN ACCOUNT
+    CURRENCY_VND = "704".freeze        # ISO 4217
+    COUNTRY_VN   = "VN".freeze
+
+    module_function
+
+    # bank_bin: the Napas BIN (`client.get_banks` → "bin", same value create_va takes).
+    # account_number: the REAL account from confirm_va — where the money lands.
+    # amount: integer VND; nil or 0 mints an open-amount QR the payer fills in.
+    # description: the transfer memo; normalized (see #normalize_description).
+    def payload(bank_bin:, account_number:, amount: nil, description: nil)
+      beneficiary = tlv("00", validate_id!(bank_bin, "bank_bin")) +
+                    tlv("01", validate_id!(account_number, "account_number"))
+      merchant    = tlv("00", NAPAS_AID) + tlv("01", beneficiary) + tlv("02", SERVICE_CODE)
+      memo        = normalize_description(description)
+      dong        = validate_amount!(amount)
+
+      s  = "000201"          # payload format indicator
+      s += "010211"          # point of initiation: 11 = static/reusable (12 = single-use)
+      s += tlv("38", merchant)
+      s += tlv("53", CURRENCY_VND)
+      # `if amount` alone would be a porting bug: 0 is falsy in the JS original but
+      # truthy in Ruby, which would emit a bogus zero-amount field 54.
+      s += tlv("54", dong.to_s) if dong.positive?
+      s += tlv("58", COUNTRY_VN)
+      s += tlv("62", tlv("08", memo)) unless memo.empty?
+      s += "6304"            # CRC tag + length, both covered by their own checksum
+      s + crc16(s)
+    end
+
+    # ASCII-folds Vietnamese diacritics and truncates to MAX_DESCRIPTION, because many
+    # bank scanners mangle or reject a non-ASCII memo.
+    #
+    # PERSIST WHAT THIS RETURNS. "Thanh toán" becomes "Thanh toan", so a webhook matcher
+    # grepping your original un-normalized string silently misses every payment.
+    def normalize_description(str)
+      normalized =
+        str.to_s
+           # A Latin-1 paste or a byte-truncated memo would otherwise raise a raw
+           # ArgumentError out of unicode_normalize, past any rescue Tingee::Error.
+           .encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+           .unicode_normalize(:nfkd) # NFKD, not NFD: also folds fullwidth ＨＤ１ to HD1
+           .gsub(/\p{Mn}/, "")       # drop combining diacritics: "toán" -> "toan"
+           .tr("đĐ", "dD")           # not decomposable, needs its own mapping
+           # Anything still non-ASCII becomes a space rather than vanishing, so an
+           # en dash or NBSP cannot silently fuse two words into one.
+           .gsub(/[^\x20-\x7E]/, " ")
+           .squeeze(" ")
+           .strip[0, MAX_DESCRIPTION]
+           .strip                    # truncation can leave a trailing space mid-word
+
+      # An unreferenced QR is unmatchable by construction (the auto-confirm matcher
+      # keys on this memo), so refuse to turn a memo the caller meant into nothing.
+      if normalized.empty? && !str.to_s.strip.empty?
+        raise Error.new("QR_INPUT", "description #{str.inspect} normalized to empty; a QR with no memo cannot be matched")
+      end
+
+      normalized
+    end
+
+    # VND has no minor unit, so an amount must be a whole non-negative number of dong.
+    # Deliberately NOT String#to_i, which coerces instead of parsing: "1.234.567" is
+    # the ordinary Vietnamese money format and to_i turns it into a 1-dong QR that the
+    # payer scans, pays, and nobody notices. nil (or 0) means an open-amount QR.
+    def validate_amount!(amount)
+      return 0 if amount.nil?
+
+      dong = case amount
+             when Numeric then (amount % 1).zero? ? amount.to_i : nil # Float/BigDecimal/Rational
+             when String  then amount.match?(/\A\d+\z/) ? amount.to_i : nil
+             end
+      raise Error.new("QR_INPUT", "amount must be a whole non-negative number of dong, got #{amount.inspect}") if dong.nil? || dong.negative?
+
+      dong
+    end
+
+    # EMVCo TLV: 2-char id + 2-char length + value. The length counts BYTES — the JS
+    # original used String#length (UTF-16 units), which diverges on any non-ASCII value.
+    def tlv(id, value)
+      size = value.bytesize
+      raise Error.new("QR_INPUT", "#{id} value is #{size} bytes; EMVCo length field holds 2 digits") if size > 99
+
+      "#{id}#{format('%02d', size)}#{value}"
+    end
+
+    # CRC16-CCITT-FALSE: init 0xFFFF, poly 0x1021, no reflection, no final XOR.
+    # Masked once at the end rather than each round — Ruby Integers are unbounded, so
+    # the intermediate width differs from JS's 32-bit bitwise ops, the low 16 bits do not.
+    def crc16(str)
+      crc = 0xFFFF
+      str.each_byte do |byte|
+        crc ^= byte << 8
+        8.times { crc = (crc & 0x8000).zero? ? crc << 1 : (crc << 1) ^ 0x1021 }
+      end
+      format("%04X", crc & 0xFFFF)
+    end
+
+    # Bank BIN and account number must survive a QR scan into a bank app's transfer
+    # form, so reject anything but ASCII alphanumerics. No BIN whitelist here —
+    # client.get_banks is the source of truth for what Tingee actually supports.
+    def validate_id!(value, name)
+      value = value.to_s
+      raise Error.new("QR_INPUT", "#{name} must be non-empty ASCII alphanumerics, got #{value.inspect}") unless value.match?(/\A[A-Za-z0-9]+\z/)
+
+      value
+    end
+  end
+end

data/lib/tingee.rb

@@ -0,0 +1,30 @@
+# Ruby client for the Tingee BaaS API (https://open-api.tingee.vn) — bank account
+# linking, virtual accounts, and payment webhooks. Pure Ruby, zero runtime
+# dependencies, no Rails required (guarded by test/tingee/rails_free_boundary_test.rb).
+#
+# The observed API contract lives in docs/tingee-api-reference.md (signing recipe,
+# envelope shapes, error codes — all verified against the live API 2026-07-16).
+# Credentials are INJECTED via Tingee.configure; this library never reads any
+# credential store itself.
+require_relative "tingee/version"
+require_relative "tingee/error"
+require_relative "tingee/configuration"
+require_relative "tingee/signature"
+require_relative "tingee/viet_qr"
+require_relative "tingee/client"
+
+module Tingee
+  class << self
+    def configure
+      yield config
+      config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    # test seam — swap in a fake config, reset between examples
+    attr_writer :config
+  end
+end

data/lib/tingee_ruby_sdk.rb

@@ -0,0 +1,2 @@
+# Bundler autorequires by gem name; the library lives under lib/tingee.
+require_relative "tingee"

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: tingee_ruby_sdk
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- lpwanw
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Pure-Ruby, zero-dependency client for Tingee (open-api.tingee.vn): HMAC-SHA512
+  request signing, bank-link sessions, the manual create-va/confirm-va OTP chain,
+  unlink, and raw-body webhook signature verification. Built from a live-verified
+  API contract.'
+email:
+- lp.wanw@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/bank-auto-confirm-integration-guide.md
+- docs/tingee-api-reference.md
+- docs/tingee-vcb-personal-link.md
+- lib/tingee.rb
+- lib/tingee/client.rb
+- lib/tingee/configuration.rb
+- lib/tingee/error.rb
+- lib/tingee/signature.rb
+- lib/tingee/version.rb
+- lib/tingee/viet_qr.rb
+- lib/tingee_ruby_sdk.rb
+homepage: https://github.com/lpwanw/tingee_ruby_sdk
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/lpwanw/tingee_ruby_sdk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Ruby client for the Tingee BaaS API — bank linking, virtual accounts, payment
+  webhooks
+test_files: []