kkhay 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ede43e8b5ffcadeb0e7530a569edad2b57f3bb323f30bdec176d392aadbf9247
+  data.tar.gz: 18122defec338469717ffadc0aa4e4bef274c2755878d713311dd24d0c1298f8
+SHA512:
+  metadata.gz: 0c46a4d00454e5cab9a627b7e4a6d324ae77e9ef1615490202b15f82d2de621cce1711795f84889a70a7113ac39164347919723ddd5f02fe27fb4473c201fe43
+  data.tar.gz: e7695e1e945d988b207b13a308d6598393b12a9665285a147231473d6ed14a4a096d0f7123d195f07289834fd2c921c8dd9c665c71ce1d4328af46f2c77fe8cb

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 K Khay (https://kkhay.com)
+
+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,108 @@
+# K Khay Ruby Gem 💎
+
+Official Ruby gem for the **[K Khay Sovereign Crypto Payment Gateway](https://kkhay.com)**.
+
+Accept non-custodial and custodial crypto payments (USDT, USDC, BNB, ETH across BSC, Polygon, Arbitrum, Base, and Ethereum) directly in **Ruby on Rails**, Sinatra, Hanami, or standalone Ruby backends with **zero external dependencies**.
+
+---
+
+## 📦 Installation
+
+Add to your application's `Gemfile`:
+
+```ruby
+gem "kkhay"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install kkhay
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Global Rails Initializer (`config/initializers/kkhay.rb`)
+
+```ruby
+Kkhay.configure do |config|
+  config.api_key = ENV["KKHAY_API_KEY"]
+  # config.base_url = "https://api.kkhay.com" # default
+  # config.timeout = 30 # default in seconds
+end
+```
+
+### 2. Create an Invoice
+
+```ruby
+client = Kkhay.client
+
+response = client.create_invoice(
+  price_amount: 49.99,
+  price_currency: "USD",
+  pay_network: "bsc",
+  pay_token: "USDT",
+  order_id: "ORDER-7721",
+  title: "Pro Membership",
+  customer_email: "buyer@example.com",
+  redirect_url: "https://myshop.com/orders/success",
+  cancel_url: "https://myshop.com/cart"
+)
+
+invoice = response[:invoice]
+puts "Invoice ID: #{invoice[:id]}"
+puts "Hosted Checkout URL: #{invoice[:hostedUrl]}"
+```
+
+### 3. Check Invoice Status
+
+```ruby
+data = client.get_invoice("inv_9f81a7b2")
+puts "Status: #{data[:invoice][:status]}"
+
+data[:payments].each do |payment|
+  puts "Tx: #{payment[:txHash]} (#{payment[:confirmations]} confirmations)"
+end
+```
+
+---
+
+## 🔐 Webhook / IPN Verification (Rails Controller)
+
+```ruby
+class KkhayWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    payload = request.raw_post
+    signature = request.headers["x-kkhay-signature"]
+    secret = ENV["KKHAY_IPN_SECRET"]
+
+    event = Kkhay::Webhook.parse_event(payload, signature, secret)
+
+    if event[:event] == "payment.finished"
+      order = Order.find_by(id: event[:order_id])
+      order&.update!(status: "paid", tx_hash: event[:tx_hash])
+    end
+
+    head :ok
+  rescue Kkhay::SignatureVerificationError => e
+    render json: { error: e.message }, status: :bad_request
+  end
+end
+```
+
+---
+
+## 📄 License
+
+MIT © [K Khay](https://kkhay.com)
+

data/lib/kkhay/client.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Kkhay
+  class Client
+    attr_reader :api_key, :base_url, :timeout
+
+    # Initializes the K Khay Client
+    #
+    # @param api_key [String] Your merchant API key
+    # @param base_url [String] Custom gateway URL (defaults to https://api.kkhay.com)
+    # @param timeout [Integer] Timeout in seconds (defaults to 30)
+    def initialize(api_key: nil, base_url: "https://api.kkhay.com", timeout: 30)
+      @api_key = (api_key || Kkhay.configuration&.api_key).to_s.strip
+      raise ArgumentError, "Kkhay::Client: A valid 'api_key' is required." if @api_key.empty?
+
+      @base_url = (base_url || "https://api.kkhay.com").sub(%r{/+\z}, "")
+      @timeout = timeout.to_i
+    end
+
+    # Creates a new crypto payment invoice
+    #
+    # @param params [Hash] Invoice parameters (:price_amount, :pay_network, :pay_token, etc.)
+    # @return [Hash] Parsed response containing invoice details and hosted_url
+    def create_invoice(params)
+      price = params[:price_amount] || params["priceAmount"]
+      network = params[:pay_network] || params["payNetwork"]
+      token = params[:pay_token] || params["payToken"]
+
+      raise ArgumentError, "create_invoice: :price_amount must be greater than 0" if price.to_f <= 0
+      raise ArgumentError, "create_invoice: :pay_network is required (e.g. 'bsc', 'polygon')" if network.to_s.empty?
+      raise ArgumentError, "create_invoice: :pay_token is required (e.g. 'USDT', 'USDC')" if token.to_s.empty?
+
+      payload = {
+        priceAmount: price.to_f,
+        payNetwork: network.to_s,
+        payToken: token.to_s,
+        priceCurrency: (params[:price_currency] || params["priceCurrency"] || "USD").to_s,
+      }
+
+      payload[:orderId] = (params[:order_id] || params["orderId"]).to_s if params[:order_id] || params["orderId"]
+      payload[:title] = (params[:title] || params["title"]).to_s if params[:title] || params["title"]
+      payload[:customerName] = (params[:customer_name] || params["customerName"]).to_s if params[:customer_name] || params["customerName"]
+      payload[:customerEmail] = (params[:customer_email] || params["customerEmail"]).to_s if params[:customer_email] || params["customerEmail"]
+      payload[:redirectUrl] = (params[:redirect_url] || params["redirectUrl"]).to_s if params[:redirect_url] || params["redirectUrl"]
+      payload[:cancelUrl] = (params[:cancel_url] || params["cancelUrl"]).to_s if params[:cancel_url] || params["cancelUrl"]
+      payload[:ipnCallbackUrl] = (params[:ipn_callback_url] || params["ipnCallbackUrl"]).to_s if params[:ipn_callback_url] || params["ipnCallbackUrl"]
+      payload[:metadata] = params[:metadata] if params[:metadata]
+
+      request("/v1/merchant/invoices", method: :post, body: payload)
+    end
+
+    # Retrieves an invoice by UUID
+    #
+    # @param invoice_id [String] The unique invoice ID
+    # @return [Hash] Invoice details and blockchain confirmations
+    def get_invoice(invoice_id)
+      raise ArgumentError, "get_invoice: invoice_id is required" if invoice_id.to_s.strip.empty?
+
+      request("/v1/merchant/invoices/#{URI.encode_www_form_component(invoice_id.to_s.strip)}", method: :get)
+    end
+
+    # Lists and paginates merchant invoices
+    #
+    # @param query [Hash] Filtering and pagination options (:page, :limit, :status, :search)
+    # @return [Hash] Paginated invoice records
+    def list_invoices(query = {})
+      query_params = {}
+      query_params["page"] = query[:page] || query["page"] if query[:page] || query["page"]
+      query_params["limit"] = query[:limit] || query["limit"] if query[:limit] || query["limit"]
+      query_params["status"] = query[:status] || query["status"] if query[:status] || query["status"]
+      query_params["search"] = query[:search] || query["search"] if query[:search] || query["search"]
+
+      query_str = query_params.empty? ? "" : "?#{URI.encode_www_form(query_params)}"
+      request("/v1/merchant/invoices#{query_str}", method: :get)
+    end
+
+    # Checks the health of the gateway
+    def check_health
+      request("/health", method: :get)
+    end
+
+    private
+
+    def build_url(path)
+      clean = path.start_with?("/") ? path : "/#{path}"
+      if @base_url.end_with?("/api") || @base_url.include?("api.")
+        "#{@base_url}#{clean}"
+      else
+        "#{@base_url}/api#{clean}"
+      end
+    end
+
+    def request(path, method: :get, body: nil)
+      uri = URI.parse(build_url(path))
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      req = case method
+            when :post then Net::HTTP::Post.new(uri.request_uri)
+            else Net::HTTP::Get.new(uri.request_uri)
+            end
+
+      req["Accept"] = "application/json"
+      req["x-api-key"] = @api_key
+      req["User-Agent"] = "kkhay-ruby/#{Kkhay::VERSION}"
+
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      response = http.request(req)
+      parsed = JSON.parse(response.body, symbolize_names: true) rescue {}
+
+      status_code = response.code.to_i
+      if status_code >= 400
+        msg = parsed[:message] || parsed[:error] || "HTTP #{status_code} Error"
+        raise ApiError.new(status_code, msg, parsed[:code], parsed[:details])
+      end
+
+      parsed
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise ApiError.new(408, "Request timed out after #{@timeout}s")
+    rescue ApiError
+      raise
+    rescue StandardError => e
+      raise ApiError.new(500, "Network error: #{e.message}")
+    end
+  end
+end
+

data/lib/kkhay/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kkhay
+  class Error < StandardError; end
+
+  class ApiError < Error
+    attr_reader :status, :code, :details
+
+    def __initialize__(status, message, code = nil, details = nil)
+      @status = status
+      @code = code
+      @details = details
+      super("Kkhay::ApiError [HTTP #{status}]: #{message}")
+    end
+
+    def initialize(status, message, code = nil, details = nil)
+      @status = status
+      @code = code
+      @details = details
+      super("Kkhay::ApiError [HTTP #{status}]: #{message}")
+    end
+  end
+
+  class SignatureVerificationError < Error; end
+end
+

data/lib/kkhay/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Kkhay
+  VERSION = "1.0.0"
+end
+

data/lib/kkhay/webhook.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Kkhay
+  module Webhook
+    class << self
+      # Verifies the cryptographic HMAC-SHA256 signature sent with incoming K Khay IPN webhooks.
+      #
+      # @param payload [String, Hash] The raw request body or hash
+      # @param signature [String] The x-kkhay-signature header value
+      # @param ipn_secret [String] Your merchant IPN Secret Key
+      # @return [Boolean] true if signature matches
+      def verify_signature(payload, signature, ipn_secret)
+        return false if signature.nil? || signature.to_s.strip.empty? || ipn_secret.nil? || ipn_secret.to_s.strip.empty?
+
+        raw_body = payload.is_a?(String) ? payload : JSON.generate(payload)
+        expected = OpenSSL::HMAC.hexdigest("SHA256", ipn_secret.to_s, raw_body)
+
+        secure_compare(expected, signature.to_s.strip)
+      rescue StandardError
+        false
+      end
+
+      # Validates and parses incoming webhook payload into a Ruby Hash with symbolize_names.
+      #
+      # @raise [SignatureVerificationError] if signature is invalid
+      def parse_event(raw_body, signature, ipn_secret)
+        unless verify_signature(raw_body, signature, ipn_secret)
+          raise SignatureVerificationError, "Invalid K Khay webhook signature: Request rejected."
+        end
+
+        JSON.parse(raw_body, symbolize_names: true)
+      rescue JSON::ParserError => e
+        raise ArgumentError, "Failed to parse webhook JSON payload: #{e.message}"
+      end
+
+      private
+
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack("C*")
+        r = b.unpack("C*")
+        res = 0
+        l.each_with_index do |byte, i|
+          res |= byte ^ r[i]
+        end
+        res.zero?
+      end
+    end
+  end
+end
+

data/lib/kkhay.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "kkhay/version"
+require_relative "kkhay/errors"
+require_relative "kkhay/webhook"
+require_relative "kkhay/client"
+
+module Kkhay
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+
+    def initialize
+      @api_key = nil
+      @base_url = "https://api.kkhay.com"
+      @timeout = 30
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Convenience method to instantiate a new client
+    def client(api_key: nil, base_url: nil, timeout: nil)
+      Client.new(
+        api_key: api_key || configuration.api_key,
+        base_url: base_url || configuration.base_url,
+        timeout: timeout || configuration.timeout
+      )
+    end
+  end
+end
+

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: kkhay
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- K Khay
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-06 00:00:00.000000000 Z
+dependencies: []
+description: Accept non-custodial and custodial crypto payments (USDT, USDC, BNB,
+  ETH on BSC, Polygon, Arbitrum, Base, Ethereum) in Ruby on Rails applications.
+email:
+- dev@kkhay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kkhay.rb
+- lib/kkhay/client.rb
+- lib/kkhay/errors.rb
+- lib/kkhay/version.rb
+- lib/kkhay/webhook.rb
+homepage: https://kkhay.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://kkhay.com
+  source_code_uri: https://github.com/boboaungdev/kkhay-ruby
+  changelog_uri: https://github.com/boboaungdev/kkhay-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/boboaungdev/kkhay-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby Gem for K Khay Sovereign Crypto Payment Gateway
+test_files: []