kkhay 1.0.0 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ede43e8b5ffcadeb0e7530a569edad2b57f3bb323f30bdec176d392aadbf9247
-  data.tar.gz: 18122defec338469717ffadc0aa4e4bef274c2755878d713311dd24d0c1298f8
+  metadata.gz: 65dfcca8ac26b07ae0023a248e95ca76d91969b27ed573cba5183cb08ce17476
+  data.tar.gz: a1df4eab611a02bdf56654389c6f671a83c6d0e71eff71f01f4134df84976f85
 SHA512:
-  metadata.gz: 0c46a4d00454e5cab9a627b7e4a6d324ae77e9ef1615490202b15f82d2de621cce1711795f84889a70a7113ac39164347919723ddd5f02fe27fb4473c201fe43
-  data.tar.gz: e7695e1e945d988b207b13a308d6598393b12a9665285a147231473d6ed14a4a096d0f7123d195f07289834fd2c921c8dd9c665c71ce1d4328af46f2c77fe8cb
+  metadata.gz: d8179fa57f292f15e16699a06ed0f1a1740d58987b6a2780d24bc563b3ff0c586baabae5fcf416a9c84652966e6ba09d71218a0ae8d083de39b3ae85f4dc96cb
+  data.tar.gz: 2934108cec17df46ad821619677171914a5f53498834fcc54e8bc77443555af1f90c9f7ae90b5a1536b4fbab1592def09480c8eb20482723f4fdb9ab368f50ca

data/README.md

@@ -1,8 +1,23 @@
 # K Khay Ruby Gem 💎
 
-Official Ruby gem for the **[K Khay Sovereign Crypto Payment Gateway](https://kkhay.com)**.
+[![Gem Version](https://badge.fury.io/rb/kkhay.svg)](https://badge.fury.io/rb/kkhay)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D3.0.0-red.svg)](https://www.ruby-lang.org/)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/boboaungdev/kkhay-ruby/ci.yml?branch=main&label=CI)](https://github.com/boboaungdev/kkhay-ruby/actions)
 
-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**.
+Official Ruby gem for the **[K Khay Gateway](https://kkhay.com)** — the sovereign cryptocurrency payment gateway.
+
+Accept sovereign, non-custodial crypto payments (**USDT, USDC, BTC, ETH, SOL, TON, BNB, TRX, DOGE, XRP, LTC** across **190+ blockchain networks**) directly in **Ruby on Rails**, Sinatra, Hanami, or standalone Ruby backends with **zero external dependencies**.
+
+---
+
+## 🌟 Highlights
+
+* **Zero External Dependencies**: Built strictly using Ruby's standard library (`net/http`, `openssl`, `json`, `uri`).
+* **190+ Blockchain Networks**: Native support for EVM chains (BNB Chain, Polygon, Arbitrum, Base, Ethereum), Solana, TON, Tron, Bitcoin, XRPL, Dogecoin, and Litecoin.
+* **Database Enum Alignment**: Strictly aligned with gateway invoice states (`WAITING`, `PAID`, `EXPIRED`, `CANCELED`).
+* **Timing-Safe HMAC Verification**: Built-in webhook signature validation preventing timing attacks.
+* **Rails Ready**: Seamless integration with Rails initializers and ActiveSupport.
 
 ---
 
@@ -14,13 +29,13 @@ Add to your application's `Gemfile`:
 gem "kkhay"
 ```
 
-And then execute:
+And execute:
 
 ```bash
 bundle install
 ```
 
-Or install it directly:
+Or install it directly via `gem`:
 
 ```bash
 gem install kkhay
@@ -45,11 +60,10 @@ end
 ```ruby
 client = Kkhay.client
 
+# Dynamic multi-currency checkout:
 response = client.create_invoice(
-  price_amount: 49.99,
-  price_currency: "USD",
-  pay_network: "bsc",
-  pay_token: "USDT",
+  amount: 49.99,
+  currency: "USD",
   order_id: "ORDER-7721",
   title: "Pro Membership",
   customer_email: "buyer@example.com",
@@ -62,14 +76,33 @@ puts "Invoice ID: #{invoice[:id]}"
 puts "Hosted Checkout URL: #{invoice[:hostedUrl]}"
 ```
 
+Or create an invoice locked to a specific cryptocurrency and chain:
+
+```ruby
+response = client.create_invoice(
+  amount: 50.00,
+  currency: "USD",
+  pay_network: "solana",
+  pay_token: "USDC",
+  order_id: "ORDER-7722"
+)
+```
+
 ### 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)"
+status = data[:invoice][:status]
+
+case status
+when Kkhay::Status::PAID
+  puts "Payment confirmed on-chain!"
+when Kkhay::Status::WAITING
+  puts "Waiting for customer payment..."
+when Kkhay::Status::EXPIRED
+  puts "Invoice expired."
+when Kkhay::Status::CANCELED
+  puts "Invoice canceled."
 end
 ```
 
@@ -77,20 +110,31 @@ end
 
 ## 🔐 Webhook / IPN Verification (Rails Controller)
 
+Verify incoming webhook requests from K Khay Gateway with timing-safe HMAC-SHA256 signatures:
+
 ```ruby
+# app/controllers/kkhay_webhooks_controller.rb
 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"]
+    secret = ENV["KKHAY_WEBHOOK_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])
+    case event[:event]
+    when "invoice.paid"
+      order = Order.find_by(id: event.dig(:data, :orderId))
+      order&.update!(
+        status: "paid",
+        tx_hash: event.dig(:data, :txHash),
+        amount_paid: event.dig(:data, :amountPaid)
+      )
+    when "invoice.expired"
+      order = Order.find_by(id: event.dig(:data, :orderId))
+      order&.update!(status: "expired")
     end
 
     head :ok
@@ -102,7 +146,37 @@ end
 
 ---
 
+## 🌐 Supported Cryptocurrencies & Networks
+
+Supports 190+ blockchain networks and 500+ cryptocurrencies:
+
+| Ecosystem | Networks | Supported Assets |
+| :--- | :--- | :--- |
+| **BNB Smart Chain** | BSC Mainnet, BSC Testnet | USDT, USDC, BNB, and BEP-20 tokens |
+| **Polygon** | Polygon PoS, Amoy Testnet | USDT, USDC, POL, and ERC-20 tokens |
+| **Arbitrum** | Arbitrum One, Nova, Sepolia | USDT, USDC, ETH, ARB |
+| **Base** | Base Mainnet, Base Sepolia | USDC, ETH, and Base tokens |
+| **Ethereum** | Ethereum Mainnet, Sepolia | USDT, USDC, ETH, and ERC-20 tokens |
+| **Solana** | Solana Mainnet, Devnet | SOL, USDT, USDC, and SPL tokens |
+| **TON** | TON Mainnet, Testnet | TON, USDT, and Jettons |
+| **Tron** | Tron Mainnet, Shasta | TRX, USDT (TRC-20), USDC |
+| **Bitcoin** | Bitcoin Mainnet, Testnet | BTC |
+| **XRPL** | XRP Ledger Mainnet, Testnet | XRP |
+| **Dogecoin** | Dogecoin Mainnet | DOGE |
+| **Litecoin** | Litecoin Mainnet | LTC |
+
+---
+
+## ⚙️ Configuration Reference
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_key` | `String` | **Required** | Your K Khay Gateway API Key. |
+| `base_url` | `String` | `"https://api.kkhay.com"` | Base Gateway API URL. |
+| `timeout` | `Integer` | `30` | Request timeout in seconds. |
+
+---
+
 ## 📄 License
 
 MIT © [K Khay](https://kkhay.com)
-

data/lib/kkhay/client.rb

@@ -8,9 +8,9 @@ module Kkhay
   class Client
     attr_reader :api_key, :base_url, :timeout
 
-    # Initializes the K Khay Client
+    # Initializes the K Khay Gateway Client
     #
-    # @param api_key [String] Your merchant API key
+    # @param api_key [String] Your gateway 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)
@@ -23,34 +23,55 @@ module Kkhay
 
     # 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
+    # @param params [Hash] Invoice parameters (:amount, :currency, :pay_network, :pay_token, etc.)
+    # @return [Hash] Parsed response containing invoice details and hostedUrl
     def create_invoice(params)
-      price = params[:price_amount] || params["priceAmount"]
-      network = params[:pay_network] || params["payNetwork"]
-      token = params[:pay_token] || params["payToken"]
+      price = params[:price_amount] || params[:amount] || params["priceAmount"] || params["amount"]
+      raise ArgumentError, "create_invoice: :amount or :price_amount must be greater than 0" if price.nil? || price.to_f <= 0
 
-      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?
+      currency = (params[:price_currency] || params[:currency] || params["priceCurrency"] || params["currency"] || "USD").to_s.upcase
 
       payload = {
+        amount: price.to_f,
         priceAmount: price.to_f,
-        payNetwork: network.to_s,
-        payToken: token.to_s,
-        priceCurrency: (params[:price_currency] || params["priceCurrency"] || "USD").to_s,
+        currency: currency,
+        priceCurrency: currency,
       }
 
-      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]
+      network = params[:pay_network] || params[:network] || params["payNetwork"] || params["network"]
+      payload[:payNetwork] = network.to_s if network && !network.to_s.strip.empty?
 
-      request("/v1/merchant/invoices", method: :post, body: payload)
+      token = params[:pay_token] || params[:token] || params["payToken"] || params["token"]
+      payload[:payToken] = token.to_s if token && !token.to_s.strip.empty?
+
+      order_id = params[:order_id] || params["orderId"]
+      payload[:orderId] = order_id.to_s if order_id
+
+      title = params[:title] || params["title"]
+      payload[:title] = title.to_s if title
+
+      description = params[:description] || params["description"]
+      payload[:description] = description.to_s if description
+
+      customer_name = params[:customer_name] || params["customerName"]
+      payload[:customerName] = customer_name.to_s if customer_name
+
+      customer_email = params[:customer_email] || params["customerEmail"]
+      payload[:customerEmail] = customer_email.to_s if customer_email
+
+      redirect_url = params[:redirect_url] || params[:return_url] || params["redirectUrl"] || params["returnUrl"]
+      payload[:redirectUrl] = redirect_url.to_s if redirect_url
+
+      cancel_url = params[:cancel_url] || params["cancelUrl"]
+      payload[:cancelUrl] = cancel_url.to_s if cancel_url
+
+      ipn_callback_url = params[:ipn_callback_url] || params[:callback_url] || params["ipnCallbackUrl"] || params["callbackUrl"]
+      payload[:ipnCallbackUrl] = ipn_callback_url.to_s if ipn_callback_url
+
+      metadata = params[:metadata]
+      payload[:metadata] = metadata if metadata
+
+      request("/v1/gateway/invoices", method: :post, body: payload)
     end
 
     # Retrieves an invoice by UUID
@@ -60,10 +81,10 @@ module Kkhay
     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)
+      request("/v1/gateway/invoices/#{URI.encode_www_form_component(invoice_id.to_s.strip)}", method: :get)
     end
 
-    # Lists and paginates merchant invoices
+    # Lists and paginates gateway invoices
     #
     # @param query [Hash] Filtering and pagination options (:page, :limit, :status, :search)
     # @return [Hash] Paginated invoice records
@@ -75,7 +96,7 @@ module Kkhay
       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)
+      request("/v1/gateway/invoices#{query_str}", method: :get)
     end
 
     # Checks the health of the gateway
@@ -134,4 +155,3 @@ module Kkhay
     end
   end
 end
-

data/lib/kkhay/status.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kkhay
+  module Status
+    WAITING  = "WAITING"
+    PAID     = "PAID"
+    EXPIRED  = "EXPIRED"
+    CANCELED = "CANCELED"
+
+    ALL = [WAITING, PAID, EXPIRED, CANCELED].freeze
+
+    def self.valid?(status)
+      ALL.include?(status.to_s.upcase)
+    end
+  end
+end
+

data/lib/kkhay/version.rb

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

data/lib/kkhay/webhook.rb

@@ -10,13 +10,13 @@ module Kkhay
       #
       # @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
+      # @param secret [String] Your gateway Webhook/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?
+      def verify_signature(payload, signature, secret)
+        return false if signature.nil? || signature.to_s.strip.empty? || secret.nil? || 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)
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, raw_body)
 
         secure_compare(expected, signature.to_s.strip)
       rescue StandardError
@@ -25,9 +25,13 @@ module Kkhay
 
       # Validates and parses incoming webhook payload into a Ruby Hash with symbolize_names.
       #
+      # @param raw_body [String] The raw request body
+      # @param signature [String] The x-kkhay-signature header value
+      # @param secret [String] Your gateway Webhook/IPN Secret Key
+      # @return [Hash] Parsed webhook payload
       # @raise [SignatureVerificationError] if signature is invalid
-      def parse_event(raw_body, signature, ipn_secret)
-        unless verify_signature(raw_body, signature, ipn_secret)
+      def parse_event(raw_body, signature, secret)
+        unless verify_signature(raw_body, signature, secret)
           raise SignatureVerificationError, "Invalid K Khay webhook signature: Request rejected."
         end
 
@@ -39,17 +43,22 @@ module Kkhay
       private
 
       def secure_compare(a, b)
-        return false unless a.bytesize == b.bytesize
+        if OpenSSL.respond_to?(:fixed_length_secure_compare)
+          return false unless a.bytesize == b.bytesize
+
+          OpenSSL.fixed_length_secure_compare(a, b)
+        else
+          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]
+          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
-        res.zero?
       end
     end
   end
 end
-

data/lib/kkhay.rb

@@ -2,6 +2,7 @@
 
 require_relative "kkhay/version"
 require_relative "kkhay/errors"
+require_relative "kkhay/status"
 require_relative "kkhay/webhook"
 require_relative "kkhay/client"
 
@@ -41,4 +42,3 @@ module Kkhay
     end
   end
 end
-

metadata

@@ -1,19 +1,47 @@
 --- !ruby/object:Gem::Specification
 name: kkhay
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.4
 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.
+date: 2026-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Accept sovereign cryptocurrency payments (USDT, USDC, BTC, ETH, SOL,
+  TON, BNB, TRX, DOGE, XRP, LTC across 190+ chains) in Ruby and Rails applications.
 email:
-- dev@kkhay.com
+- support@kkhay.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -23,6 +51,7 @@ files:
 - lib/kkhay.rb
 - lib/kkhay/client.rb
 - lib/kkhay/errors.rb
+- lib/kkhay/status.rb
 - lib/kkhay/version.rb
 - lib/kkhay/webhook.rb
 homepage: https://kkhay.com
@@ -48,8 +77,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Official Ruby Gem for K Khay Sovereign Crypto Payment Gateway
+summary: Official Ruby Gem for K Khay Gateway
 test_files: []