bakong-open-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ab8db3ca6526ebf0abf3c6541dd573fb4b673db087d9c0292cf067b2fff2a04
+  data.tar.gz: 8f33be1f488d42ff0a6482d575a58b631da19236c0f69e08c03c3e556b339e93
+SHA512:
+  metadata.gz: 3d84f6150fbd46b48b87f9ba7c44d2a9d50df6246699b3a09919a9fd240d40decc24ab2701e970bb149641bbc97ae5287cb90f9d8ceac1505ad5995c9d015653
+  data.tar.gz: e6df0b93e85cc4f0c861a40a92c08e2f88dcb6c8906ae093db2fcdd20a6d70c3fbced2a4ea90abfd8c0314e984c5f9025c1d61f0ccb5befc23d3273a60c5ab19

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to **bakong-open-api** 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).
+
+## [Unreleased]
+
+### Added
+- Initial scaffolding for the Bakong Open API Ruby client.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandy Sodanheang
+
+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,261 @@
+# bakong-open-api
+
+[![Gem Version](https://badge.fury.io/rb/bakong-open-api.svg?icon=si%3Arubygems)](https://rubygems.org/gems/bakong-open-api)
+
+A Ruby client for the **Bakong Open API** — the National Bank of Cambodia's
+HTTP API for verifying KHQR transactions, checking Bakong account existence,
+generating wallet deep links, and managing access tokens.
+
+> ⚠️ **Unofficial client.** This gem is **not** an official SDK from the
+> National Bank of Cambodia or any Bakong-affiliated entity. It is an
+> independent, community-maintained Ruby wrapper implemented against the
+> publicly available API documentation at
+> <https://api-bakong.nbc.gov.kh/document>. The NBC has not reviewed,
+> endorsed, or sponsored this project. Always verify behavior against the
+> upstream documentation before relying on it in production.
+
+Zero runtime gem dependencies — uses only the Ruby standard library
+(`Net::HTTP`). Pairs naturally with [bakong-khqr](https://rubygems.org/gems/bakong-khqr)
+for generating the KHQR payloads you then verify.
+
+## Requirements
+
+- Ruby `>= 3.4.1`
+- A registered Bakong developer email (request one via the NBC's developer
+  portal). The email is used to mint short-lived JWT access tokens via
+  `POST /v1/renew_token`.
+
+## Installation
+
+```ruby
+gem "bakong-open-api"
+```
+
+Or:
+
+```sh
+gem install bakong-open-api
+```
+
+```ruby
+require "bakong/open_api"
+```
+
+## Quick start
+
+```ruby
+client = Bakong::OpenApi.client
+
+# 1. Mint a token using your registered email
+client.token = client.tokens.renew(email: "you@example.com").fetch(:token)
+
+# 2. Check whether a Bakong account exists
+client.accounts.exists?(account_id: "vandy@aclb")
+# => true | false
+
+# 3. Verify a transaction by the MD5 of its KHQR string
+client.transactions.check_by_md5(md5: "d60f3db96913029a2af979a1662c1e72")
+# => { hash: "...", from_account_id: "...", to_account_id: "...",
+#      currency: "USD", amount: 1.0, description: "",
+#      created_date_ms: 1605774370608.0, acknowledged_date_ms: 1605774422421.0 }
+# nil if the API returns errorCode 1 (not found)
+
+# 4. Generate a wallet deep link for a KHQR
+client.deeplinks.generate(qr: "00020101...")
+# => { short_link: "https://bakong.link/abc" }
+```
+
+## Authentication
+
+Every endpoint except `tokens.renew` and `deeplinks.generate` requires a
+Bearer token. Tokens are short-lived JWTs (~90 days at the time of writing).
+Two ways to use them:
+
+```ruby
+# Construct with token
+client = Bakong::OpenApi.client(token: "eyJhbGciOiJ...")
+
+# Or set/replace after construction (e.g. after refresh)
+client.token = "eyJhbGciOiJ..."
+```
+
+To mint a fresh token:
+
+```ruby
+response = client.tokens.renew(email: "vandysodanheang@gmail.com")
+client.token = response[:token]
+```
+
+## Resources
+
+### `client.tokens`
+
+| Method | Bakong endpoint | Returns |
+| --- | --- | --- |
+| `.renew(email:)` | `POST /v1/renew_token` | `{ token: String }` |
+
+### `client.accounts`
+
+| Method | Bakong endpoint | Returns |
+| --- | --- | --- |
+| `.exists?(account_id:)` | `POST /v1/check_bakong_account` | `true` / `false` |
+
+### `client.deeplinks`
+
+```ruby
+source = Bakong::OpenApi::SourceInfo.new(
+  app_icon_url: "https://yourapp.example/icon.png",
+  app_name: "Your App",
+  app_deep_link_callback: "yourapp://payment-result"
+)
+
+client.deeplinks.generate(qr: "00020101...", source_info: source)
+# => { short_link: "..." }
+```
+
+`source_info` is optional; when provided, **all three fields are required**
+and the gem raises `Bakong::OpenApi::MissingFieldsError` before the HTTP
+call if any are blank.
+
+### `client.transactions`
+
+| Method | Bakong endpoint | Returns |
+| --- | --- | --- |
+| `.check_by_md5(md5:)` | `POST /v1/check_transaction_by_md5` | transaction `Hash` or `nil` |
+| `.check_by_hash(hash:)` | `POST /v1/check_transaction_by_hash` | transaction `Hash` or `nil` |
+| `.check_by_short_hash(hash:, amount:, currency:)` | `POST /v1/check_transaction_by_short_hash` | transaction `Hash` or `nil` |
+| `.check_by_instruction_ref(instruction_ref:)` | `POST /v1/check_transaction_by_instruction_ref` | transaction `Hash` or `nil` |
+| `.check_by_external_ref(external_ref:)` | `POST /v1/check_transaction_by_external_ref` | transaction `Hash` or `nil` |
+| `.check_by_md5_list(md5s:)` | `POST /v1/check_transaction_by_md5_list` | full envelope `Hash` (data is per-row Array) |
+| `.check_by_hash_list(hashes:)` | `POST /v1/check_transaction_by_hash_list` | full envelope `Hash` (data is per-row Array) |
+
+**Single lookups** return the transaction `Hash` with snake_cased keys on
+success, `nil` when the API reports `errorCode 1` (transaction not found), and
+raise on every other failure. **Batch lookups** are capped at 50 items and
+return the full envelope so callers can iterate per-row statuses (`SUCCESS`,
+`NOT_FOUND`, `FAILED`, `STATIC_QR`).
+
+## Error handling
+
+All errors inherit from `Bakong::OpenApi::Error` and carry the HTTP status,
+the Bakong `responseCode` / `errorCode` / `responseMessage`, and the raw
+response body:
+
+```ruby
+begin
+  client.tokens.renew(email: "wrong@example.com")
+rescue Bakong::OpenApi::NotRegisteredError => e
+  e.error_code      # => 10
+  e.response_message # => "Not registered yet"
+  e.body            # => { responseCode: 1, errorCode: 10, ... }
+end
+```
+
+Specialized error classes for each Bakong errorCode:
+
+| errorCode | Class | Meaning |
+| --- | --- | --- |
+| 1 | `TransactionNotFoundError` | Transaction not found (also returned as `nil` from single lookups) |
+| 2 | `StaticQrNotSupportedError` | Static QR codes aren't supported by this endpoint |
+| 3 | `TransactionFailedError` | The transaction failed |
+| 4 | `DeeplinkProviderError` | Upstream deep link provider error |
+| 5 | `MissingFieldsError` | Required request fields missing |
+| 6 | `UnauthorizedError` | Token missing or rejected |
+| 7 | `EmailServerDownError` | Bakong couldn't send the email |
+| 8 | `EmailAlreadyRegisteredError` | Email already registered |
+| 9 | `BakongUnreachableError` | Bakong reports it can't reach its backend |
+| 10 | `NotRegisteredError` | This email isn't registered |
+| 11 | `AccountNotFoundError` | Bakong account doesn't exist (also returned as `false` from `accounts.exists?`) |
+| 12 | `AccountInvalidError` | Bakong account ID malformed |
+
+Transport-level errors map to:
+
+| HTTP status | Class |
+| --- | --- |
+| 401 | `AuthenticationError` |
+| 403 | `TokenExpiredError` |
+| 404 | `NotFoundError` |
+| 429 | `RateLimitError` |
+| 4xx | `InvalidRequestError` |
+| 5xx | `ServerError` |
+| socket / DNS failure | `ConnectionError` |
+
+## Configuration
+
+```ruby
+client = Bakong::OpenApi.client(
+  token: "eyJhbGciOiJ...",
+  base_url: "https://api-bakong.nbc.gov.kh",  # default
+  open_timeout: 45,                            # seconds
+  read_timeout: 45,
+  user_agent: "myapp/1.2.3"
+)
+```
+
+## Pairing with bakong-khqr
+
+The typical flow when accepting Bakong payments is:
+
+```ruby
+require "bakong/khqr"
+require "bakong/open_api"
+
+# Generate a KHQR string for the buyer to scan
+info = Bakong::Khqr::IndividualInfo.new(
+  bakong_account_id: "vandy@aclb",
+  merchant_name: "Sodanheang Coffee",
+  merchant_city: "Phnom Penh",
+  amount: 1.50,
+  currency: Bakong::Khqr::CURRENCY[:usd],
+  expiration_timestamp: (Time.now.to_f * 1000).to_i + 5 * 60 * 1000
+)
+qr_data = Bakong::Khqr.generate_merchant(info)
+qr_data[:qr]   # → display this as a QR image
+qr_data[:md5]  # → store this; poll it later
+
+# Later (e.g. via a background job), check whether the buyer paid
+client = Bakong::OpenApi.client(token: ENV.fetch("BAKONG_TOKEN"))
+transaction = client.transactions.check_by_md5(md5: qr_data[:md5])
+if transaction
+  # paid — fulfill the order
+else
+  # not yet paid (or expired)
+end
+```
+
+## Development
+
+```sh
+bin/setup        # bundle install
+bundle exec rspec
+bundle exec rake # default task = spec
+bin/console      # IRB with bakong/open_api loaded
+```
+
+## Releasing
+
+```sh
+bin/release v0.1.1
+```
+
+The script bumps `VERSION`, runs RSpec, builds the gem, commits + tags,
+prompts for your RubyGems MFA OTP, pushes the gem to RubyGems, pushes the
+git tag, and creates a GitHub release. Requires `$RUBY_GEM_KEY` in your
+shell and an authenticated `gh` CLI.
+
+## Contributing
+
+Issues and pull requests are welcome at
+<https://github.com/VandyTheCoder/bakong-open-api-ruby>.
+
+## Credits & disclaimer
+
+This is an **independent, unofficial Ruby client** built against the public
+[Bakong Open API documentation](https://api-bakong.nbc.gov.kh/document)
+published by the National Bank of Cambodia. The NBC has not reviewed,
+endorsed, or sponsored this project. All trademarks and API specifications
+remain the property of the National Bank of Cambodia.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/bakong-open-api.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/bakong/open_api/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "bakong-open-api"
+  spec.version       = Bakong::OpenApi::VERSION
+  spec.authors       = ["Vandy Sodanheang"]
+  spec.email         = ["vandysodanheang@gmail.com"]
+
+  spec.summary       = "Unofficial Ruby client for the Bakong Open API (National Bank of Cambodia)."
+  spec.description   = <<~DESC
+    An unofficial, community-maintained Ruby client for the Bakong Open API
+    published by the National Bank of Cambodia. This gem is NOT an official
+    SDK from the NBC or any Bakong-affiliated entity — it is implemented
+    independently against the public API documentation available at
+    https://api-bakong.nbc.gov.kh/document.
+
+    Authenticate, manage tokens, look up Bakong accounts, verify transactions
+    by md5/hash/short-hash/external ref/instruction ref, and generate KHQR
+    deep links. Zero runtime gem dependencies — uses only the Ruby standard
+    library (Net::HTTP).
+  DESC
+  spec.homepage      = "https://github.com/VandyTheCoder/bakong-open-api-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-open-api.gemspec"]
+  end
+  spec.require_paths = ["lib"]
+  spec.bindir        = "exe"
+  spec.executables   = []
+end

data/lib/bakong/open_api/client.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "connection"
+require_relative "resources/tokens"
+require_relative "resources/accounts"
+require_relative "resources/deeplinks"
+require_relative "resources/transactions"
+
+module Bakong
+  module OpenApi
+    # Primary entry-point. Holds configuration and a Connection. Resource
+    # modules (tokens, accounts, deeplinks, transactions) are lazily
+    # instantiated on first access.
+    class Client
+      attr_reader :config, :connection
+
+      def initialize(token: nil, base_url: nil, open_timeout: nil, read_timeout: nil, user_agent: nil)
+        @config = Configuration.new
+        @config.token = token if token
+        @config.base_url = base_url if base_url
+        @config.open_timeout = open_timeout if open_timeout
+        @config.read_timeout = read_timeout if read_timeout
+        @config.user_agent = user_agent if user_agent
+        @connection = Connection.new(@config)
+      end
+
+      # Mutate the active token after construction (e.g. after renew_token).
+      def token=(new_token)
+        @config.token = new_token
+      end
+
+      def tokens
+        @tokens ||= Resources::Tokens.new(self)
+      end
+
+      def accounts
+        @accounts ||= Resources::Accounts.new(self)
+      end
+
+      def deeplinks
+        @deeplinks ||= Resources::Deeplinks.new(self)
+      end
+
+      def transactions
+        @transactions ||= Resources::Transactions.new(self)
+      end
+    end
+  end
+end

data/lib/bakong/open_api/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Bakong
+  module OpenApi
+    # Client-wide configuration. Either passed to Client.new explicitly or
+    # mutated via Bakong::OpenApi.configure { |c| ... } for a thread-local
+    # default singleton.
+    class Configuration
+      DEFAULT_BASE_URL = "https://api-bakong.nbc.gov.kh"
+      DEFAULT_TIMEOUT = 45
+
+      attr_accessor :base_url, :token, :open_timeout, :read_timeout, :user_agent
+
+      def initialize
+        @base_url = DEFAULT_BASE_URL
+        @open_timeout = DEFAULT_TIMEOUT
+        @read_timeout = DEFAULT_TIMEOUT
+        @user_agent = "bakong-open-api-ruby/#{Bakong::OpenApi::VERSION}"
+      end
+    end
+  end
+end

data/lib/bakong/open_api/connection.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "error"
+
+module Bakong
+  module OpenApi
+    # Net::HTTP-based HTTP transport. Knows nothing about Bakong domain
+    # semantics — just turns (method, path, body) into a parsed Hash or raises
+    # a Bakong::OpenApi::Error.
+    class Connection
+      def initialize(config)
+        @config = config
+      end
+
+      def get(path, params: nil, headers: {})
+        request(:get, path, params: params, headers: headers)
+      end
+
+      def post(path, body: nil, headers: {})
+        request(:post, path, body: body, headers: headers)
+      end
+
+      private
+
+      def request(method, path, body: nil, params: nil, headers: {})
+        uri = build_uri(path, params)
+        http = build_http(uri)
+        req = build_request(method, uri, body, headers)
+
+        response = http.request(req)
+        handle(response)
+      rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH => e
+        raise ConnectionError.new("Bakong Open API unreachable: #{e.class}: #{e.message}")
+      end
+
+      def build_uri(path, params)
+        uri = URI.parse(@config.base_url)
+        uri.path = path.start_with?("/") ? path : "/#{path}"
+        uri.query = URI.encode_www_form(params) if params && !params.empty?
+        uri
+      end
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @config.open_timeout
+        http.read_timeout = @config.read_timeout
+        http
+      end
+
+      def build_request(method, uri, body, headers)
+        klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
+        req = klass.new(uri.request_uri)
+        req["Content-Type"] = "application/json"
+        req["Accept"] = "application/json"
+        req["User-Agent"] = @config.user_agent
+        req["Authorization"] = "Bearer #{@config.token}" if @config.token
+        headers.each { |k, v| req[k] = v }
+        req.body = JSON.generate(body) if body
+        req
+      end
+
+      def handle(response)
+        body = parse(response.body)
+
+        case response.code.to_i
+        when 200..299
+          body
+        when 401
+          raise AuthenticationError.new("authentication required", status: 401, body: body)
+        when 403
+          raise TokenExpiredError.new("token expired or insufficient scope", status: 403, body: body)
+        when 404
+          raise NotFoundError.new("resource not found", status: 404, body: body)
+        when 429
+          raise RateLimitError.new("rate limit exceeded", status: 429, body: body)
+        when 400..499
+          raise InvalidRequestError.new(error_message(body, "invalid request"), status: response.code.to_i, body: body)
+        when 500..599
+          raise ServerError.new(error_message(body, "Bakong server error"), status: response.code.to_i, body: body)
+        else
+          raise Error.new("unexpected HTTP #{response.code}", status: response.code.to_i, body: body)
+        end
+      end
+
+      def parse(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        { raw: body }
+      end
+
+      def error_message(body, fallback)
+        return fallback unless body.is_a?(Hash)
+
+        body[:message] || body[:errorMessage] || body[:error] || fallback
+      end
+    end
+  end
+end

data/lib/bakong/open_api/error.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Bakong
+  module OpenApi
+    # Base class for every error this gem raises. Carries the upstream HTTP
+    # status, the Bakong responseCode/errorCode if the API supplied one, and
+    # the raw response body for debugging.
+    class Error < StandardError
+      attr_reader :status, :response_code, :error_code, :response_message, :body
+
+      def initialize(message = nil, status: nil, response_code: nil, error_code: nil, response_message: nil, body: nil)
+        @status = status
+        @response_code = response_code
+        @error_code = error_code
+        @response_message = response_message
+        @body = body
+        super(message || response_message || "Bakong Open API error")
+      end
+    end
+
+    # HTTP-level failures
+    class AuthenticationError < Error; end   # 401
+    class TokenExpiredError < Error; end     # 403
+    class InvalidRequestError < Error; end   # 4xx
+    class NotFoundError < Error; end         # 404
+    class RateLimitError < Error; end        # 429
+    class ServerError < Error; end           # 5xx
+    class ConnectionError < Error; end       # socket timeout / DNS
+
+    # Bakong domain errors — when responseCode != 0 and the failure mode is
+    # specific enough to warrant its own class.
+    class TransactionNotFoundError < Error; end          # errorCode: 1
+    class StaticQrNotSupportedError < Error; end         # errorCode: 2
+    class TransactionFailedError < Error; end            # errorCode: 3
+    class DeeplinkProviderError < Error; end             # errorCode: 4
+    class MissingFieldsError < Error; end                # errorCode: 5
+    class UnauthorizedError < Error; end                 # errorCode: 6
+    class EmailServerDownError < Error; end              # errorCode: 7
+    class EmailAlreadyRegisteredError < Error; end       # errorCode: 8
+    class BakongUnreachableError < Error; end            # errorCode: 9
+    class NotRegisteredError < Error; end                # errorCode: 10
+    class AccountNotFoundError < Error; end              # errorCode: 11
+    class AccountInvalidError < Error; end               # errorCode: 12
+
+    # Mapping from Bakong's numeric errorCode (in the response body) to a
+    # specific error class. Used by resources that want to translate domain
+    # failures into Ruby exceptions instead of returning the raw envelope.
+    DOMAIN_ERROR_CLASSES = {
+      1  => TransactionNotFoundError,
+      2  => StaticQrNotSupportedError,
+      3  => TransactionFailedError,
+      4  => DeeplinkProviderError,
+      5  => MissingFieldsError,
+      6  => UnauthorizedError,
+      7  => EmailServerDownError,
+      8  => EmailAlreadyRegisteredError,
+      9  => BakongUnreachableError,
+      10 => NotRegisteredError,
+      11 => AccountNotFoundError,
+      12 => AccountInvalidError
+    }.freeze
+  end
+end

data/lib/bakong/open_api/helpers/case_helper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Bakong
+  module OpenApi
+    module Helpers
+      # Convert between Ruby's snake_case (used everywhere in this gem's
+      # public API) and the Bakong API's camelCase wire format. Recursive on
+      # hashes and arrays.
+      module CaseHelper
+        module_function
+
+        # snake_case symbol/string keys → camelCase symbol keys for requests.
+        def to_camel(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(k, v), out| out[snake_to_camel(k.to_s).to_sym] = to_camel(v) }
+          when Array
+            value.map { |v| to_camel(v) }
+          else
+            value
+          end
+        end
+
+        # camelCase keys → snake_case symbol keys for responses.
+        def to_snake(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(k, v), out| out[camel_to_snake(k.to_s).to_sym] = to_snake(v) }
+          when Array
+            value.map { |v| to_snake(v) }
+          else
+            value
+          end
+        end
+
+        def snake_to_camel(string)
+          parts = string.split("_")
+          ([parts.first] + parts.drop(1).map(&:capitalize)).join
+        end
+
+        def camel_to_snake(string)
+          string
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+        end
+      end
+    end
+  end
+end

data/lib/bakong/open_api/resources/accounts.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Bakong
+  module OpenApi
+    module Resources
+      # `POST /v1/check_bakong_account` — check whether a Bakong account ID
+      # (e.g. "user@bank") exists. The API returns responseCode 0 when the
+      # account exists, 1 + errorCode 11 when it does not. This wrapper
+      # collapses that into a Ruby boolean.
+      class Accounts < Base
+        # @param account_id [String] Bakong account ID, e.g. "vandy@aclb"
+        # @return [Boolean] true if the account exists, false if not
+        # @raise [Bakong::OpenApi::AccountInvalidError] when errorCode 12
+        # @raise [Bakong::OpenApi::Error] on other failures
+        def exists?(account_id:)
+          envelope = connection.post(
+            "/v1/check_bakong_account",
+            body: { accountId: account_id }
+          )
+          response_code = envelope[:responseCode] || envelope[:response_code]
+          error_code = envelope[:errorCode] || envelope[:error_code]
+          message = envelope[:responseMessage] || envelope[:response_message]
+
+          return true  if response_code.to_i.zero?
+          return false if error_code.to_i == 11 # explicitly NOT_FOUND
+
+          klass = Bakong::OpenApi::DOMAIN_ERROR_CLASSES[error_code.to_i] || Bakong::OpenApi::Error
+          raise klass.new(message,
+                          response_code: response_code, error_code: error_code,
+                          response_message: message, body: envelope)
+        end
+      end
+    end
+  end
+end

data/lib/bakong/open_api/resources/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../helpers/case_helper"
+
+module Bakong
+  module OpenApi
+    module Resources
+      # Shared behavior for resource modules. Each resource gets a `client`
+      # accessor (so `connection` and `config` are reachable) and helpers for
+      # turning a Bakong envelope `{responseCode, errorCode, responseMessage, data}`
+      # into either snake_cased data or a raised domain-specific Error.
+      class Base
+        def initialize(client)
+          @client = client
+        end
+
+        attr_reader :client
+
+        protected
+
+        def connection
+          @client.connection
+        end
+
+        # Submit a POST and translate the Bakong envelope into either:
+        #   - the snake_cased `data` payload on responseCode 0
+        #   - a raised domain Error on responseCode 1
+        #
+        # @param treat_response_code_1_as [nil, :not_found] when :not_found,
+        #   responseCode 1 with no specific errorCode mapping returns nil
+        #   instead of raising (used by transaction lookups).
+        def submit(path, body, treat_response_code_1_as: nil)
+          envelope = connection.post(path, body: Helpers::CaseHelper.to_camel(body))
+          unwrap(envelope, treat_response_code_1_as: treat_response_code_1_as)
+        end
+
+        # Submit and return the full snake_cased envelope without unwrapping.
+        # Used by list endpoints whose `data` is an array of mixed-status rows.
+        def submit_envelope(path, body)
+          envelope = connection.post(path, body: Helpers::CaseHelper.to_camel(body))
+          Helpers::CaseHelper.to_snake(envelope)
+        end
+
+        def unwrap(envelope, treat_response_code_1_as: nil)
+          response_code = envelope[:responseCode] || envelope[:response_code]
+          return Helpers::CaseHelper.to_snake(envelope[:data]) if response_code.to_i.zero?
+
+          error_code = envelope[:errorCode] || envelope[:error_code]
+          message = envelope[:responseMessage] || envelope[:response_message]
+          return nil if treat_response_code_1_as == :not_found && error_code.to_i == 1
+
+          klass = Bakong::OpenApi::DOMAIN_ERROR_CLASSES[error_code.to_i] || Bakong::OpenApi::Error
+          raise klass.new(message,
+                          response_code: response_code, error_code: error_code,
+                          response_message: message, body: envelope)
+        end
+      end
+    end
+  end
+end

data/lib/bakong/open_api/resources/deeplinks.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../source_info"
+
+module Bakong
+  module OpenApi
+    module Resources
+      # `POST /v1/generate_deeplink_by_qr` — turn a KHQR string into a short
+      # link the user's wallet app can open directly.
+      class Deeplinks < Base
+        # @param qr [String] KHQR payload (typically generated by the
+        #   bakong-khqr gem)
+        # @param source_info [Bakong::OpenApi::SourceInfo, nil] optional; if
+        #   provided, all three fields must be set
+        # @return [Hash] { short_link: "https://..." }
+        # @raise [Bakong::OpenApi::MissingFieldsError] if source_info is
+        #   present but incomplete
+        # @raise [Bakong::OpenApi::DeeplinkProviderError] on upstream failure
+        def generate(qr:, source_info: nil)
+          if source_info && !source_info.complete?
+            raise MissingFieldsError.new(
+              "source_info requires app_icon_url, app_name, and app_deep_link_callback",
+              error_code: 5
+            )
+          end
+
+          body = { qr: qr }
+          body[:source_info] = source_info.to_payload if source_info
+
+          submit("/v1/generate_deeplink_by_qr", body)
+        end
+      end
+    end
+  end
+end

data/lib/bakong/open_api/resources/tokens.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Bakong
+  module OpenApi
+    module Resources
+      # `POST /v1/renew_token` — exchange a registered email address for a
+      # short-lived JWT access token. The token is also delivered to the
+      # registered inbox; the API returns it inline on success.
+      class Tokens < Base
+        # @param email [String] registered Bakong developer email (max 30 chars)
+        # @return [Hash] { token: "..." }
+        # @raise [Bakong::OpenApi::Error] on any non-success responseCode
+        def renew(email:)
+          submit("/v1/renew_token", { email: email })
+        end
+      end
+    end
+  end
+end

data/lib/bakong/open_api/resources/transactions.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Bakong
+  module OpenApi
+    module Resources
+      # Bakong transaction lookups. Five single-record endpoints + two batch
+      # endpoints. Single-record lookups return the transaction Hash on
+      # success, `nil` when the API reports errorCode 1 (not found), and
+      # raise on any other failure. Batch endpoints return the full array of
+      # per-item results so the caller can introspect statuses.
+      class Transactions < Base
+        # Single transaction by MD5 of the KHQR string.
+        def check_by_md5(md5:)
+          submit("/v1/check_transaction_by_md5", { md5: md5 }, treat_response_code_1_as: :not_found)
+        end
+
+        # Single transaction by 64-char full hash.
+        def check_by_hash(hash:)
+          submit("/v1/check_transaction_by_hash", { hash: hash }, treat_response_code_1_as: :not_found)
+        end
+
+        # Single transaction by 8-char short hash. Requires amount + currency
+        # to disambiguate.
+        # @param currency [String] "USD" or "KHR"
+        def check_by_short_hash(hash:, amount:, currency:)
+          submit(
+            "/v1/check_transaction_by_short_hash",
+            { hash: hash, amount: amount, currency: currency },
+            treat_response_code_1_as: :not_found
+          )
+        end
+
+        # Single transaction by instruction reference (1-35 chars).
+        def check_by_instruction_ref(instruction_ref:)
+          submit(
+            "/v1/check_transaction_by_instruction_ref",
+            { instruction_ref: instruction_ref },
+            treat_response_code_1_as: :not_found
+          )
+        end
+
+        # Single transaction by external reference / merchant ID (1-35 chars).
+        def check_by_external_ref(external_ref:)
+          submit(
+            "/v1/check_transaction_by_external_ref",
+            { external_ref: external_ref },
+            treat_response_code_1_as: :not_found
+          )
+        end
+
+        # Batch lookup by up to 50 MD5 hashes. Returns the full envelope so
+        # callers can iterate per-row statuses (SUCCESS / NOT_FOUND / STATIC_QR).
+        # @param md5s [Array<String>]
+        # @return [Hash] full snake_cased envelope; the [:data] key is an Array
+        def check_by_md5_list(md5s:)
+          validate_batch_size!(md5s, "md5s")
+          envelope = connection.post("/v1/check_transaction_by_md5_list", body: md5s)
+          Helpers::CaseHelper.to_snake(envelope)
+        end
+
+        # Batch lookup by up to 50 full hashes. Returns the full envelope so
+        # callers can iterate per-row statuses (SUCCESS / NOT_FOUND / FAILED).
+        # @param hashes [Array<String>]
+        # @return [Hash] full snake_cased envelope; the [:data] key is an Array
+        def check_by_hash_list(hashes:)
+          validate_batch_size!(hashes, "hashes")
+          envelope = connection.post("/v1/check_transaction_by_hash_list", body: hashes)
+          Helpers::CaseHelper.to_snake(envelope)
+        end
+
+        private
+
+        def validate_batch_size!(array, field_name)
+          raise ArgumentError, "#{field_name} must be an Array" unless array.is_a?(Array)
+          raise ArgumentError, "#{field_name} cannot be empty" if array.empty?
+          raise ArgumentError, "#{field_name} cannot exceed 50 items (got #{array.size})" if array.size > 50
+        end
+      end
+    end
+  end
+end

data/lib/bakong/open_api/source_info.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Bakong
+  module OpenApi
+    # Optional metadata sent alongside a deep-link generation request so the
+    # receiving wallet can render the originating app's icon and name.
+    SourceInfo = Struct.new(:app_icon_url, :app_name, :app_deep_link_callback, keyword_init: true) do
+      def complete?
+        [app_icon_url, app_name, app_deep_link_callback].all? { |v| v.is_a?(String) && !v.empty? }
+      end
+
+      def to_payload
+        {
+          app_icon_url: app_icon_url,
+          app_name: app_name,
+          app_deep_link_callback: app_deep_link_callback
+        }
+      end
+    end
+  end
+end

data/lib/bakong/open_api/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Bakong
+  module OpenApi
+    VERSION = "0.1.0"
+  end
+end

data/lib/bakong/open_api.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "open_api/version"
+require_relative "open_api/error"
+require_relative "open_api/configuration"
+require_relative "open_api/connection"
+require_relative "open_api/source_info"
+require_relative "open_api/client"
+
+module Bakong
+  # Unofficial Ruby client for the Bakong Open API (National Bank of Cambodia).
+  # This gem is not an official SDK from the NBC — it is implemented against
+  # the public API documentation at https://api-bakong.nbc.gov.kh/document.
+  module OpenApi
+    class << self
+      # Convenience constructor: `Bakong::OpenApi.client(token: "...")`.
+      def client(**kwargs)
+        Client.new(**kwargs)
+      end
+    end
+  end
+end

data/lib/bakong-open-api.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "bakong/open_api"

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: bakong-open-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vandy Sodanheang
+bindir: exe
+cert_chain: []
+date: 2026-05-16 00:00:00.000000000 Z
+dependencies: []
+description: |
+  An unofficial, community-maintained Ruby client for the Bakong Open API
+  published by the National Bank of Cambodia. This gem is NOT an official
+  SDK from the NBC or any Bakong-affiliated entity — it is implemented
+  independently against the public API documentation available at
+  https://api-bakong.nbc.gov.kh/document.
+
+  Authenticate, manage tokens, look up Bakong accounts, verify transactions
+  by md5/hash/short-hash/external ref/instruction ref, and generate KHQR
+  deep links. Zero runtime gem dependencies — uses only the Ruby standard
+  library (Net::HTTP).
+email:
+- vandysodanheang@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bakong-open-api.gemspec
+- lib/bakong-open-api.rb
+- lib/bakong/open_api.rb
+- lib/bakong/open_api/client.rb
+- lib/bakong/open_api/configuration.rb
+- lib/bakong/open_api/connection.rb
+- lib/bakong/open_api/error.rb
+- lib/bakong/open_api/helpers/case_helper.rb
+- lib/bakong/open_api/resources/accounts.rb
+- lib/bakong/open_api/resources/base.rb
+- lib/bakong/open_api/resources/deeplinks.rb
+- lib/bakong/open_api/resources/tokens.rb
+- lib/bakong/open_api/resources/transactions.rb
+- lib/bakong/open_api/source_info.rb
+- lib/bakong/open_api/version.rb
+homepage: https://github.com/VandyTheCoder/bakong-open-api-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/VandyTheCoder/bakong-open-api-ruby
+  changelog_uri: https://github.com/VandyTheCoder/bakong-open-api-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/VandyTheCoder/bakong-open-api-ruby/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Unofficial Ruby client for the Bakong Open API (National Bank of Cambodia).
+test_files: []