nakopay 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7131b4098aa2562030d2fe2a9074d8216295f34a2d2dc358cd9458a6fabf117c
+  data.tar.gz: 4c7e39254fe0adeb19afa282c6ad07cb4afb55bfd554712a50128db47f34b368
+SHA512:
+  metadata.gz: 2490d3896553cbec2c4306b3fc4cd4517beb339e9fbd92f2beb9c2a0acb20b00bc717221b63ef1e01a38f2ec40c71108158ae197f652293b50e61effdc32af7e
+  data.tar.gz: b94643da6e7608d20eafbc38a117aecc3cf400520e2498241942c798d2079732675f94149ad8fe98263fa2b2d63fda616ae65c42ad344d7e5e95dc2f2364086b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NakoPay
+
+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,65 @@
+# nakopay (Ruby gem)
+
+Official [NakoPay](https://nakopay.com) SDK for Ruby.
+
+```bash
+gem install nakopay
+```
+
+## Quick start
+
+```ruby
+require "nakopay"
+
+NakoPay.api_key = ENV["NAKOPAY_SECRET_KEY"]
+
+invoice = NakoPay::Invoice.create(
+  amount:         "19.99",
+  currency:       "USD",
+  coin:           "BTC",
+  description:    "Pro plan",
+  customer_email: "alex@acme.com",
+  idempotency_key: "ord_1042",
+)
+
+puts invoice.id, invoice.checkout_url
+```
+
+## Features
+
+- Pinned to API version `2025-04-20`
+- Auto-retry on `429` / `5xx` with exponential backoff + jitter
+- Auto-generated `Idempotency-Key` for every POST
+- Webhook signature verifier: `NakoPay::Webhook.construct_event(payload, sig_header, secret)`
+- Typed errors: `NakoPay::APIError`, `NakoPay::SignatureVerificationError`
+
+## Webhooks
+
+```ruby
+post "/webhook" do
+  payload = request.body.read
+  begin
+    event = NakoPay::Webhook.construct_event(
+      payload,
+      request.env["HTTP_X_NAKOPAY_SIGNATURE"],
+      ENV.fetch("NAKOPAY_WEBHOOK_SECRET"),
+    )
+  rescue NakoPay::SignatureVerificationError
+    halt 400
+  end
+
+  fulfill(event["data"]["object"]) if event["type"] == "invoice.paid"
+  status 200
+end
+```
+
+## Links
+
+- [NakoPay Website](https://nakopay.com)
+- [Documentation](https://nakopay.com/docs)
+- [Integration Guide](https://nakopay.com/docs/ruby)
+- [API Reference](https://nakopay.com/docs/api-reference)
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

data/lib/nakopay/client.rb

@@ -0,0 +1,167 @@
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module NakoPay
+  # Low-level HTTP client. Most callers use the resource modules
+  # (NakoPay::Invoice, etc.) instead of touching this directly.
+  class Client
+    DEFAULT_BASE_URL    = "https://api.nakopay.com/v1"
+    DEFAULT_API_VERSION = "2025-04-20"
+    DEFAULT_TIMEOUT     = 30
+    DEFAULT_MAX_RETRIES = 3
+
+    attr_reader :api_key, :base_url, :api_version, :timeout, :max_retries
+
+    # @param faraday [Faraday::Connection, nil] optional Faraday connection for
+    #   custom middleware stacks. When provided, Net::HTTP is not used.
+    def initialize(api_key: nil, base_url: nil, api_version: nil, timeout: nil, max_retries: nil, faraday: nil)
+      @api_key     = api_key     || NakoPay.api_key
+      @base_url    = (base_url   || NakoPay.base_url    || DEFAULT_BASE_URL).chomp("/")
+      @api_version = api_version || NakoPay.api_version || DEFAULT_API_VERSION
+      @timeout     = timeout     || NakoPay.timeout     || DEFAULT_TIMEOUT
+      @max_retries = max_retries || NakoPay.max_retries || DEFAULT_MAX_RETRIES
+      @faraday     = faraday
+
+      raise ArgumentError, "NakoPay: api_key is required" if @api_key.nil? || @api_key.empty?
+      if @api_key.start_with?("pk_")
+        raise ArgumentError, "NakoPay: a publishable key (pk_*) was passed to the server SDK; use a secret key (sk_live_* or sk_test_*)"
+      end
+    end
+
+    def request(method, path, body: nil, query: nil, idempotency_key: nil, headers: {})
+      attempt = 0
+      loop do
+        begin
+          code, raw, resp_headers = execute_request(method, path, body: body, query: query, idempotency_key: idempotency_key, headers: headers)
+        rescue StandardError => e
+          if attempt < @max_retries
+            sleep_with_backoff(attempt, nil)
+            attempt += 1
+            next
+          end
+          raise NakoPay::ConnectionError, "network error: #{e.message}"
+        end
+
+        if code >= 200 && code < 300
+          return raw.empty? ? nil : JSON.parse(raw)
+        end
+
+        env = (JSON.parse(raw) rescue {})
+        api_err_payload = env.is_a?(Hash) ? env["error"] : nil
+        api_err_payload ||= { "code" => "http_#{code}", "message" => raw.empty? ? "HTTP #{code}" : raw }
+        if api_err_payload.is_a?(Hash) && api_err_payload["request_id"].nil?
+          api_err_payload["request_id"] = resp_headers && resp_headers["x-request-id"]
+        end
+
+        if (code == 429 || code >= 500) && attempt < @max_retries
+          sleep_with_backoff(attempt, nil)
+          attempt += 1
+          next
+        end
+
+        raise NakoPay.build_api_error(api_err_payload, status_code: code)
+      end
+    end
+
+    private
+
+    def execute_request(method, path, body:, query:, idempotency_key:, headers:)
+      if @faraday
+        execute_faraday(method, path, body: body, query: query, idempotency_key: idempotency_key, headers: headers)
+      else
+        execute_net_http(method, path, body: body, query: query, idempotency_key: idempotency_key, headers: headers)
+      end
+    end
+
+    def execute_net_http(method, path, body:, query:, idempotency_key:, headers:)
+      uri = URI(@base_url + path)
+      uri.query = URI.encode_www_form(query.compact) if query && !query.empty?
+
+      req = build_request(method, uri, body: body, idempotency_key: idempotency_key, headers: headers)
+      res = http_for(uri).request(req)
+      h = {}
+      res.each_header { |k, v| h[k.downcase] = v }
+      [res.code.to_i, res.body.to_s, h]
+    end
+
+    def execute_faraday(method, path, body:, query:, idempotency_key:, headers:)
+      url = @base_url + path
+      h = default_headers.merge(headers)
+      if %w[POST DELETE].include?(method.to_s.upcase)
+        h["Idempotency-Key"] = idempotency_key || "idem_#{SecureRandom.hex(16)}"
+      end
+
+      resp = @faraday.run_request(method.to_s.downcase.to_sym, url, body ? JSON.generate(body) : nil, h) do |req|
+        req.params.update(query.compact) if query && !query.empty?
+        req.headers["Content-Type"] = "application/json" if body
+      end
+      res_h = {}
+      resp.headers.each { |k, v| res_h[k.downcase] = v }
+      [resp.status, resp.body.to_s, res_h]
+    end
+
+    def default_headers
+      {
+        "Authorization"     => "Bearer #{@api_key}",
+        "X-NakoPay-Version" => @api_version,
+        "User-Agent"        => "nakopay-ruby/#{VERSION}",
+        "Accept"            => "application/json",
+      }
+    end
+
+    def http_for(uri)
+      h = Net::HTTP.new(uri.host, uri.port)
+      h.use_ssl = uri.scheme == "https"
+      h.open_timeout = @timeout
+      h.read_timeout = @timeout
+      h
+    end
+
+    def build_request(method, uri, body:, idempotency_key:, headers:)
+      klass = case method.to_s.upcase
+              when "GET"    then Net::HTTP::Get
+              when "POST"   then Net::HTTP::Post
+              when "DELETE" then Net::HTTP::Delete
+              else raise ArgumentError, "unsupported method #{method}"
+              end
+      req = klass.new(uri.request_uri)
+      default_headers.each { |k, v| req[k] = v }
+      headers.each { |k, v| req[k] = v }
+
+      if %w[POST DELETE].include?(method.to_s.upcase)
+        req["Idempotency-Key"] = idempotency_key || "idem_#{SecureRandom.hex(16)}"
+        if body
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+      end
+      req
+    end
+
+    def sleep_with_backoff(attempt, retry_after)
+      if retry_after
+        n = Integer(retry_after) rescue nil
+        return sleep([n, 30].min) if n && n >= 0
+      end
+      base = [250 * (2**attempt), 8_000].min / 1000.0
+      jitter = base * 0.25 * (rand * 2 - 1)
+      sleep [0.05, base + jitter].max
+    end
+  end
+
+  class << self
+    attr_accessor :api_key, :base_url, :api_version, :timeout, :max_retries
+
+    # Default singleton client. Resources call into this; tests may swap it.
+    def client
+      @client ||= Client.new
+    end
+
+    # Reset the singleton (used in tests).
+    def reset_client!
+      @client = nil
+    end
+  end
+end

data/lib/nakopay/errors.rb

@@ -0,0 +1,88 @@
+module NakoPay
+  # Base error for everything raised by this SDK.
+  class Error < StandardError; end
+
+  # Raised for any non-2xx HTTP response.
+  class APIError < Error
+    attr_reader :code, :type, :param, :doc_url, :request_id, :status_code
+
+    def initialize(message:, code: nil, type: nil, param: nil, doc_url: nil, request_id: nil, status_code: nil)
+      super(message)
+      @code = code
+      @type = type
+      @param = param
+      @doc_url = doc_url
+      @request_id = request_id
+      @status_code = status_code
+    end
+
+    # True for 429/5xx errors that may succeed on retry.
+    def retryable?
+      @status_code == 429 || (@status_code && @status_code >= 500)
+    end
+  end
+
+  # Raised for 401 or authentication_error codes.
+  class AuthenticationError < APIError
+    def initialize(message: "Invalid API key", **kwargs)
+      kwargs[:code] ||= "authentication_error"
+      kwargs[:type] ||= "authentication_error"
+      super(message: message, **kwargs)
+    end
+  end
+
+  # Raised for 429 responses after all retries are exhausted.
+  class RateLimitError < APIError
+    def initialize(message: "Rate limit exceeded", **kwargs)
+      kwargs[:code] ||= "rate_limit_error"
+      kwargs[:type] ||= "rate_limit_error"
+      super(message: message, **kwargs)
+    end
+  end
+
+  # Raised when an idempotency key is reused with different parameters.
+  class IdempotencyError < APIError
+    def initialize(message: "Idempotency conflict", **kwargs)
+      kwargs[:code] ||= "idempotency_error"
+      kwargs[:type] ||= "idempotency_error"
+      super(message: message, **kwargs)
+    end
+  end
+
+  # Raised when transport fails (DNS, refused, timeout) after all retries.
+  class ConnectionError < Error; end
+
+  # Raised by Webhook.construct_event when verification fails.
+  class SignatureVerificationError < Error
+    attr_reader :code
+
+    def initialize(message, code: nil)
+      super(message)
+      @code = code
+    end
+  end
+
+  # Maps API error envelope to specialized subclass.
+  def self.build_api_error(payload, status_code:)
+    code = payload["code"]
+    message = payload["message"]
+    common = {
+      code: code,
+      type: payload["type"],
+      param: payload["param"],
+      doc_url: payload["doc_url"],
+      request_id: payload["request_id"],
+      status_code: status_code,
+    }
+
+    if status_code == 401 || code == "authentication_error"
+      AuthenticationError.new(message: message || "Invalid API key", **common)
+    elsif status_code == 429 || code == "rate_limit_error"
+      RateLimitError.new(message: message || "Rate limit exceeded", **common)
+    elsif code == "idempotency_error"
+      IdempotencyError.new(message: message || "Idempotency conflict", **common)
+    else
+      APIError.new(message: message || "Unknown error", **common)
+    end
+  end
+end

data/lib/nakopay/resource.rb

@@ -0,0 +1,23 @@
+module NakoPay
+  # Lightweight wrapper that lets callers do `inv.id` instead of `inv["id"]`.
+  class Resource
+    def initialize(attrs)
+      @attrs = attrs || {}
+    end
+
+    def [](key) = @attrs[key.to_s]
+    def to_h = @attrs.dup
+    def to_json(*) = @attrs.to_json
+
+    def respond_to_missing?(name, include_private = false)
+      @attrs.key?(name.to_s) || super
+    end
+
+    def method_missing(name, *args, &blk)
+      key = name.to_s
+      return @attrs[key] if @attrs.key?(key)
+
+      super
+    end
+  end
+end

data/lib/nakopay/resources.rb

@@ -0,0 +1,264 @@
+module NakoPay
+  module Invoice
+    module_function
+
+    def create(idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/invoices-create", body: params, idempotency_key: idempotency_key))
+    end
+
+    def retrieve(id)
+      Resource.new(NakoPay.client.request(:get, "/invoices-get", query: { id: id }))
+    end
+
+    def list(limit: nil, starting_after: nil, status: nil)
+      page = NakoPay.client.request(:get, "/invoices-list", query: { limit: limit, starting_after: starting_after, status: status })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+
+    def cancel(id, idempotency_key: nil)
+      Resource.new(NakoPay.client.request(:post, "/invoices-cancel", body: { id: id }, idempotency_key: idempotency_key))
+    end
+
+    def auto_paging_each(limit: nil, status: nil)
+      return enum_for(:auto_paging_each, limit: limit, status: status) unless block_given?
+
+      cursor = nil
+      loop do
+        page = list(limit: limit, starting_after: cursor, status: status)
+        page["data"].each { |inv| yield inv }
+        break unless page["has_more"]
+
+        cursor = page["next_cursor"] || page["data"].last&.id
+        break unless cursor
+      end
+    end
+  end
+
+  module Customer
+    module_function
+
+    def create(idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/customers", body: params, idempotency_key: idempotency_key))
+    end
+
+    def retrieve(id)
+      Resource.new(NakoPay.client.request(:get, "/customers", query: { id: id }))
+    end
+
+    def list(limit: nil, starting_after: nil)
+      page = NakoPay.client.request(:get, "/customers", query: { limit: limit, starting_after: starting_after })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+  end
+
+  module PaymentLink
+    module_function
+
+    def create(idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/payment-links", body: params, idempotency_key: idempotency_key))
+    end
+
+    def retrieve(id)
+      Resource.new(NakoPay.client.request(:get, "/payment-links", query: { id: id }))
+    end
+  end
+
+  module WebhookEndpoint
+    module_function
+
+    def create(idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/webhooks-create", body: params, idempotency_key: idempotency_key))
+    end
+
+    def delete(id, idempotency_key: nil)
+      NakoPay.client.request(:post, "/webhooks-delete", body: { id: id }, idempotency_key: idempotency_key)
+    end
+
+    def test(id, idempotency_key: nil)
+      NakoPay.client.request(:post, "/webhooks-test", body: { id: id }, idempotency_key: idempotency_key)
+    end
+
+    def replay(id, delivery_id: nil, idempotency_key: nil)
+      body = { id: id }
+      body[:delivery_id] = delivery_id if delivery_id
+      Resource.new(NakoPay.client.request(:post, "/webhooks-replay", body: body, idempotency_key: idempotency_key))
+    end
+  end
+
+  module Logs
+    module_function
+
+    def list(limit: nil, starting_after: nil, **params)
+      page = NakoPay.client.request(:get, "/logs-list", query: { limit: limit, starting_after: starting_after, **params })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+  end
+
+  module Sandbox
+    module_function
+
+    # Seed the sandbox with demo customers + invoices. Test-mode key only.
+    def seed(idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/sandbox-seed", body: params, idempotency_key: idempotency_key))
+    end
+  end
+
+  module Event
+    module_function
+
+    def list(limit: nil, starting_after: nil, type: nil)
+      page = NakoPay.client.request(:get, "/events-list", query: { limit: limit, starting_after: starting_after, type: type })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+
+    def auto_paging_each(limit: nil, type: nil)
+      return enum_for(:auto_paging_each, limit: limit, type: type) unless block_given?
+
+      cursor = nil
+      loop do
+        page = list(limit: limit, starting_after: cursor, type: type)
+        page["data"].each { |e| yield e }
+        break unless page["has_more"]
+
+        cursor = page["next_cursor"] || page["data"].last&.id
+        break unless cursor
+      end
+    end
+  end
+
+  module Rate
+    module_function
+
+    def retrieve(base: nil, quotes: nil)
+      q = { base: base }
+      q[:quotes] = quotes.join(",") if quotes && !quotes.empty?
+      Resource.new(NakoPay.client.request(:get, "/rates-get", query: q))
+    end
+  end
+
+  module Credit
+    module_function
+
+    def balance
+      Resource.new(NakoPay.client.request(:get, "/credits-balance"))
+    end
+
+    module Topup
+      module_function
+
+      def create(amount_sats:, idempotency_key: nil)
+        Resource.new(NakoPay.client.request(:post, "/credits-topup-create", body: { amount_sats: amount_sats }, idempotency_key: idempotency_key))
+      end
+
+      def retrieve(id)
+        Resource.new(NakoPay.client.request(:get, "/credits-topup-status", query: { id: id }))
+      end
+    end
+  end
+
+  module Subscription
+    module_function
+
+    def retrieve(id)
+      Resource.new(NakoPay.client.request(:get, "/subscriptions-list", query: { id: id }))
+    end
+
+    def list(limit: nil, starting_after: nil, status: nil)
+      page = NakoPay.client.request(:get, "/subscriptions-list", query: { limit: limit, starting_after: starting_after, status: status })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+
+    def cancel(id, at_period_end: true, idempotency_key: nil)
+      Resource.new(NakoPay.client.request(:post, "/subscriptions-cancel", body: { subscription_id: id, at_period_end: at_period_end }, idempotency_key: idempotency_key))
+    end
+
+    def pause(id, token: nil, idempotency_key: nil)
+      body = { subscription_id: id }
+      body[:token] = token if token
+      Resource.new(NakoPay.client.request(:post, "/subscriptions-pause", body: body, idempotency_key: idempotency_key))
+    end
+
+    def resume(id, token: nil, idempotency_key: nil)
+      body = { subscription_id: id }
+      body[:token] = token if token
+      Resource.new(NakoPay.client.request(:post, "/subscriptions-resume", body: body, idempotency_key: idempotency_key))
+    end
+
+    def portal(id, idempotency_key: nil)
+      Resource.new(NakoPay.client.request(:post, "/subscriptions-portal", body: { subscription_id: id }, idempotency_key: idempotency_key))
+    end
+
+    def auto_paging_each(limit: nil, status: nil)
+      return enum_for(:auto_paging_each, limit: limit, status: status) unless block_given?
+
+      cursor = nil
+      loop do
+        page = list(limit: limit, starting_after: cursor, status: status)
+        page["data"].each { |s| yield s }
+        break unless page["has_more"]
+
+        cursor = page["next_cursor"] || page["data"].last&.id
+        break unless cursor
+      end
+    end
+  end
+
+  module SubscriptionPlan
+    module_function
+
+    def list(limit: nil, starting_after: nil)
+      page = NakoPay.client.request(:get, "/subscription-plans-list", query: { limit: limit, starting_after: starting_after })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+  end
+
+  module Refund
+    module_function
+
+    def create(invoice_id:, idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/refunds-create", body: { invoice_id: invoice_id, **params }, idempotency_key: idempotency_key))
+    end
+
+    def retrieve(id)
+      Resource.new(NakoPay.client.request(:get, "/refunds-get", query: { id: id }))
+    end
+
+    def list(limit: nil, starting_after: nil, invoice_id: nil, status: nil)
+      page = NakoPay.client.request(:get, "/refunds-list", query: { limit: limit, starting_after: starting_after, invoice_id: invoice_id, status: status })
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+
+    def cancel(id, idempotency_key: nil)
+      Resource.new(NakoPay.client.request(:post, "/refunds-cancel", body: { id: id }, idempotency_key: idempotency_key))
+    end
+  end
+
+  module Key
+    module_function
+
+    def create(idempotency_key: nil, **params)
+      Resource.new(NakoPay.client.request(:post, "/keys-create", body: params, idempotency_key: idempotency_key))
+    end
+
+    def list
+      page = NakoPay.client.request(:get, "/keys-list")
+      page["data"] = (page["data"] || []).map { |r| Resource.new(r) }
+      page
+    end
+
+    def revoke(id, idempotency_key: nil)
+      NakoPay.client.request(:post, "/keys-revoke", body: { id: id }, idempotency_key: idempotency_key)
+    end
+
+    def rotate(id, idempotency_key: nil)
+      Resource.new(NakoPay.client.request(:post, "/keys-rotate", body: { id: id }, idempotency_key: idempotency_key))
+    end
+  end
+end

data/lib/nakopay/version.rb

@@ -0,0 +1,3 @@
+module NakoPay
+  VERSION = "1.0.0"
+end

data/lib/nakopay/webhook.rb

@@ -0,0 +1,55 @@
+require "openssl"
+require "json"
+
+module NakoPay
+  # Webhook signature verifier.
+  #
+  #   NakoPay::Webhook.construct_event(raw_body, sig_header, secret)
+  #
+  # Header format:  t=<unix>,v1=<hex_hmac>
+  # Signed payload: <t>.<raw_body>
+  module Webhook
+    DEFAULT_TOLERANCE = 300 # seconds
+
+    module_function
+
+    def construct_event(payload, sig_header, secret, tolerance: DEFAULT_TOLERANCE)
+      raise SignatureVerificationError.new("missing X-NakoPay-Signature header", code: "signature_missing") if sig_header.nil? || sig_header.empty?
+      raise SignatureVerificationError.new("webhook secret is required", code: "secret_missing") if secret.nil? || secret.empty?
+
+      parts = sig_header.split(",").each_with_object({}) do |kv, h|
+        k, v = kv.split("=", 2)
+        h[k.strip] = v.to_s.strip if k && v
+      end
+
+      ts = Integer(parts["t"]) rescue nil
+      v1 = parts["v1"]
+      raise SignatureVerificationError.new("malformed signature header", code: "signature_invalid") if ts.nil? || v1.nil? || v1.empty?
+
+      now = Time.now.to_i
+      if (now - ts).abs > tolerance
+        raise SignatureVerificationError.new("timestamp outside tolerance window", code: "signature_timestamp_outside_tolerance")
+      end
+
+      expected = OpenSSL::HMAC.hexdigest("sha256", secret, "#{ts}.#{payload}")
+      unless secure_compare(expected, v1)
+        raise SignatureVerificationError.new("signature does not match expected value", code: "signature_mismatch")
+      end
+
+      begin
+        JSON.parse(payload)
+      rescue JSON::ParserError
+        raise SignatureVerificationError.new("webhook payload is not valid JSON", code: "payload_invalid_json")
+      end
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack("C*")
+      res = 0
+      b.each_byte { |byte| res |= byte ^ l.shift }
+      res.zero?
+    end
+  end
+end

data/lib/nakopay.rb

@@ -0,0 +1,7 @@
+# Official NakoPay SDK for Ruby. See README for usage.
+require_relative "nakopay/version"
+require_relative "nakopay/errors"
+require_relative "nakopay/resource"
+require_relative "nakopay/client"
+require_relative "nakopay/webhook"
+require_relative "nakopay/resources"

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: nakopay
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- NakoPay
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-27 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client for the NakoPay crypto-payments API. Pinned to API version
+  2025-04-20.
+email:
+- sdk@nakopay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/nakopay.rb
+- lib/nakopay/client.rb
+- lib/nakopay/errors.rb
+- lib/nakopay/resource.rb
+- lib/nakopay/resources.rb
+- lib/nakopay/version.rb
+- lib/nakopay/webhook.rb
+homepage: https://github.com/NakoPayHQ/sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://nakopay.com
+  source_code_uri: https://github.com/NakoPayHQ/sdk-ruby
+  documentation_uri: https://nakopay.com/docs/sdk/ruby
+  changelog_uri: https://github.com/NakoPayHQ/sdk-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/NakoPayHQ/sdk-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'
+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 NakoPay SDK for Ruby.
+test_files: []