paymos 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd8a703e227987af0bfca337eef97398f776b82fd748b54af3ea9e2fd1d64a77
+  data.tar.gz: b5111762119eff9b677ecbf77d03425a8cf9d2252823570829d88fbf7f5f1b1f
+SHA512:
+  metadata.gz: 6d42452233f39604cffc3ff1796f1c42b30b88a1f15c63366a2bac24f5d31900b898aa47b366f3aa8195493f711b9c55ede75c894d79b5e72348fd5f33495e88
+  data.tar.gz: 0b199b07cc0334255d66af452df50641c43c8b644e8eeac9fc8f7fee749b30f467f7159e03fb3d00f4ff297d1f54c33acb96a15770c3b10b5965a07ba56c1b19

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0 - 2026-07-11
+
+- Initial official Paymos Ruby SDK.
+- Covers invoices, withdrawals, balances, system time, cursor pagination, and webhooks.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paymos
+
+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,48 @@
+# Paymos Ruby SDK
+
+Official Ruby client for the Paymos Merchant API. Its only runtime dependency is
+Ruby's official `base64` gem (required separately by modern Ruby versions).
+
+```bash
+gem install paymos
+```
+
+```ruby
+require "paymos"
+
+paymos = Paymos::Client.new(
+  api_key: ENV.fetch("PAYMOS_API_KEY"),
+  api_secret: ENV.fetch("PAYMOS_API_SECRET")
+)
+
+invoice = paymos.invoices.create(
+  project_id: "prj_...",
+  amount: "10.00",
+  currency: "USD",
+  external_order_id: "order_123"
+)
+paymos.invoices.each(status: [Paymos::InvoiceStatus::PAID]).each do |item|
+  puts item.invoice_id
+end
+balances = paymos.balances.get
+```
+
+Responses are immutable Ruby objects with documented RBS signatures; request
+keywords remain idiomatic `snake_case` and are converted directly to the Paymos
+wire contract.
+
+API failures raise typed `Paymos::ApiError` subclasses and preserve the status,
+problem fields, headers, response body, and `Retry-After`. Cursor helpers are
+lazy, bounded, and reject a repeated cursor.
+
+Never expose the API secret in a browser or mobile application. Verify webhook
+signatures against the exact raw request body before parsing JSON.
+
+```ruby
+event = Paymos::WebhookVerifier.new(ENV.fetch("PAYMOS_WEBHOOK_SECRET"))
+  .construct_event(request.env.fetch("HTTP_PAYMOS_SIGNATURE"), request.body.read)
+```
+
+Ruby 3.1 or newer is supported. See `conformance/contract.json` for the shared
+cross-language protocol contract and https://paymos.io/docs/server-sdks for the
+full API guide.

data/lib/paymos/client.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'time'
+require 'timeout'
+require 'uri'
+
+module Paymos
+  Response = Struct.new(:status, :body, :headers, keyword_init: true) do
+    def initialize(status:, body:, headers: {})
+      super(status: Integer(status), body: String(body), headers: headers.to_h.transform_values do |value|
+        String(value)
+      end.freeze)
+      freeze
+    end
+  end
+
+  class Client
+    SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+
+    attr_reader :invoices, :withdrawals, :balances, :system
+
+    def initialize(api_key:, api_secret:, base_url: 'https://api.paymos.io', timeout: 30,
+                   max_retries: 2, base_delay: 0.150, transport: nil,
+                   clock: -> { Time.now.to_i }, sleeper: ->(seconds) { sleep(seconds) }, random: Random.new)
+      raise ConfigurationError, 'api_key and api_secret are required' if api_key.to_s.empty? || api_secret.to_s.empty?
+      unless timeout.positive? && max_retries >= 0 && base_delay >= 0
+        raise ConfigurationError,
+              'timeout, max_retries, and base_delay are invalid'
+      end
+      raise ConfigurationError, 'base_url is required' if base_url.to_s.strip.empty?
+
+      @api_key = api_key
+      @api_secret = api_secret
+      origin = URI.parse(base_url)
+      unless origin.absolute? && origin.host && [nil, '',
+                                                 '/'].include?(origin.path) && origin.query.nil? && origin.fragment.nil?
+        raise ConfigurationError, 'base_url must be an absolute origin without a path'
+      end
+
+      @base_url = base_url.delete_suffix('/')
+      @timeout = timeout
+      @max_retries = max_retries
+      @base_delay = base_delay
+      @transport = transport || method(:default_transport)
+      @clock = clock
+      @sleeper = sleeper
+      @random = random
+      @invoices = Invoices.new(self)
+      @withdrawals = Withdrawals.new(self)
+      @balances = Balances.new(self)
+      @system = System.new(self)
+    end
+
+    def request(method, path, payload: nil, query: '')
+      method = method.to_s.upcase
+      body = payload.nil? ? '' : JSON.generate(payload)
+      attempts = 0
+
+      loop do
+        begin
+          timestamp = @clock.call.to_i.to_s
+          headers = {
+            'Authorization' => Signing.authorization(@api_key, @api_secret, timestamp, method, path, query, body),
+            'X-Request-Timestamp' => timestamp,
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json',
+            'User-Agent' => "paymos-ruby/#{VERSION}"
+          }
+          response = @transport.call(method, "#{@base_url}#{path}#{query}", headers, body.empty? ? nil : body, @timeout)
+        rescue IOError, SystemCallError, Timeout::Error, SocketError => e
+          if attempts < @max_retries && SAFE_METHODS.include?(method)
+            wait(attempts, nil)
+            attempts += 1
+            next
+          end
+          raise Error, "Paymos request failed: #{e.message}", cause: e
+        end
+
+        unless response.respond_to?(:status) && response.respond_to?(:body) && response.respond_to?(:headers)
+          raise Error, 'Paymos transport returned an invalid response'
+        end
+
+        if attempts < @max_retries && retryable?(method, response.status)
+          wait(attempts, header(response.headers, 'retry-after'))
+          attempts += 1
+          next
+        end
+
+        unless (200..299).cover?(response.status)
+          raise Paymos.api_error(response.status, response.body,
+                                 response.headers)
+        end
+        raise Error, 'Paymos API returned an empty response' if response.body.to_s.empty?
+
+        begin
+          return JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Error, "Paymos API returned invalid JSON: #{e.message}"
+        end
+      end
+    end
+
+    private
+
+    def default_transport(method, url, headers, body, timeout)
+      uri = URI(url)
+      request_type = Net::HTTP.const_get(method.capitalize)
+      request = request_type.new(uri)
+      headers.each { |key, value| request[key] = value }
+      request.body = body unless body.nil?
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == 'https',
+        open_timeout: timeout,
+        read_timeout: timeout
+      ) { |http| http.request(request) }
+      Response.new(status: response.code.to_i, body: response.body.to_s,
+                   headers: response.to_hash.transform_values(&:first))
+    end
+
+    def retryable?(method, status)
+      status == 429 || (status >= 500 && SAFE_METHODS.include?(method))
+    end
+
+    def wait(attempt, retry_after)
+      delay = (@base_delay * (2**attempt)) + (@random.rand * @base_delay)
+      parsed_retry_after = retry_after_seconds(retry_after)
+      delay = [delay, parsed_retry_after].max unless parsed_retry_after.nil?
+      @sleeper.call(delay)
+    end
+
+    def retry_after_seconds(value)
+      return nil if value.to_s.empty?
+      return value.to_i if value.to_s.match?(/\A\d+\z/)
+
+      [Time.httpdate(value.to_s).to_i - @clock.call.to_i, 0].max
+    rescue ArgumentError
+      nil
+    end
+
+    def header(headers, name)
+      pair = headers.to_h.find { |key, _value| key.to_s.casecmp?(name) }
+      pair&.last
+    end
+  end
+
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    def segment(value)
+      raise ArgumentError, 'Resource ID is required' unless value.is_a?(String) && !value.strip.empty?
+
+      Signing.path_segment(value)
+    end
+
+    def validate_reason(reason)
+      unless reason.is_a?(String) && reason.length.between?(1, 500) && !reason.strip.empty?
+        raise ArgumentError, 'Cancellation reason must contain 1 to 500 characters'
+      end
+
+      reason
+    end
+
+    def validate_list_filters(filters)
+      limit = filters[:limit]
+      unless limit.nil? || (limit.is_a?(Integer) && limit.between?(
+        1, 100
+      ))
+        raise ArgumentError,
+              'limit must be between 1 and 100'
+      end
+      raise ArgumentError, 'cursor cannot be empty' if filters.key?(:cursor) && filters[:cursor].to_s.empty?
+
+      statuses = filters[:status]
+      if statuses.is_a?(Array) && (statuses.empty? || statuses.uniq.length != statuses.length)
+        raise ArgumentError, 'status must be non-empty and contain no duplicates'
+      end
+
+      from = filters[:created_from]
+      to = filters[:created_to]
+      unless [from, to].compact.all? { |value| value.is_a?(Integer) && value >= 0 }
+        raise ArgumentError, 'created_from and created_to must be non-negative Unix seconds'
+      end
+      raise ArgumentError, 'created_to must be later than created_from' if from && to && from >= to
+
+      filters
+    end
+  end
+
+  class Invoices < Resource
+    def create(project_id:, amount:, currency:, external_order_id:, network: nil,
+               allow_multiple_payments: nil, customer_fee_percent: nil, client_id: nil)
+      required_keywords(project_id:, amount:, currency:, external_order_id:)
+      if !customer_fee_percent.nil? && !(customer_fee_percent.is_a?(Integer) && customer_fee_percent.between?(0, 100))
+        raise ArgumentError, 'customer_fee_percent must be between 0 and 100'
+      end
+
+      payload = { project_id:, amount:, currency:, external_order_id:, network:,
+                  allow_multiple_payments:, customer_fee_percent:, client_id: }.compact
+      Invoice.from(@client.request('POST', '/v1/invoices', payload:))
+    end
+
+    def get(invoice_id) = Invoice.from(@client.request('GET', "/v1/invoices/#{segment(invoice_id)}"))
+
+    def list(limit: nil, cursor: nil, status: nil, external_order_id: nil,
+             project_id: nil, created_from: nil, created_to: nil)
+      filters = validate_list_filters({ limit:, cursor:, status:, external_order_id:, project_id:, created_from:,
+                                        created_to: }.compact)
+      Page.from(@client.request('GET', '/v1/invoices', query: Signing.query(filters)), item_type: InvoiceListItem)
+    end
+
+    def cancel(invoice_id, reason:)
+      Invoice.from(@client.request('POST', "/v1/invoices/#{segment(invoice_id)}/cancel",
+                                   payload: { reason: validate_reason(reason) }))
+    end
+
+    def confirm_payment(invoice_id, currency:, network:)
+      required_keywords(currency:, network:)
+      Invoice.from(@client.request('POST', "/v1/invoices/#{segment(invoice_id)}/confirm-payment",
+                                   payload: { currency:, network: }))
+    end
+
+    def simulate_payment(invoice_id, stage:)
+      raise ArgumentError, 'Invalid simulation stage' unless %w[paid overpaid underpay cancel].include?(stage)
+
+      Invoice.from(@client.request('POST', "/v1/sandbox/invoices/#{segment(invoice_id)}/simulate-payment",
+                                   payload: { stage: }))
+    end
+
+    def each(max_pages: 100, **filters, &block)
+      return enum_for(__method__, max_pages: max_pages, **filters) unless block_given?
+
+      Pagination.each(method(:list), filters, max_pages:, &block)
+    end
+
+    private
+
+    def required_keywords(**values)
+      missing = values.select { |_name, value| !value.is_a?(String) || value.strip.empty? }.keys
+      raise ArgumentError, "Required values are missing: #{missing.join(', ')}" unless missing.empty?
+    end
+  end
+
+  class Withdrawals < Resource
+    def create(destination_address:, network:, currency:, amount:, external_order_id:)
+      values = { destination_address:, network:, currency:, amount:, external_order_id: }
+      missing = values.select { |_name, value| !value.is_a?(String) || value.strip.empty? }.keys
+      raise ArgumentError, "Required values are missing: #{missing.join(', ')}" unless missing.empty?
+
+      Withdrawal.from(@client.request('POST', '/v1/withdrawals', payload: values))
+    end
+
+    def get(withdrawal_id) = Withdrawal.from(@client.request('GET', "/v1/withdrawals/#{segment(withdrawal_id)}"))
+
+    def list(limit: nil, cursor: nil, status: nil, external_order_id: nil,
+             created_from: nil, created_to: nil)
+      filters = validate_list_filters({ limit:, cursor:, status:, external_order_id:, created_from:,
+                                        created_to: }.compact)
+      Page.from(@client.request('GET', '/v1/withdrawals', query: Signing.query(filters)), item_type: Withdrawal)
+    end
+
+    def cancel(withdrawal_id, reason:)
+      Withdrawal.from(@client.request('POST', "/v1/withdrawals/#{segment(withdrawal_id)}/cancel",
+                                      payload: { reason: validate_reason(reason) }))
+    end
+
+    def simulate_completion(withdrawal_id)
+      Withdrawal.from(@client.request('POST', "/v1/sandbox/withdrawals/#{segment(withdrawal_id)}/simulate-completion"))
+    end
+
+    def each(max_pages: 100, **filters, &block)
+      return enum_for(__method__, max_pages: max_pages, **filters) unless block_given?
+
+      Pagination.each(method(:list), filters, max_pages:, &block)
+    end
+  end
+
+  class Balances < Resource
+    def get = Array(@client.request('GET', '/v1/balances')).map { |item| Balance.from(item) }.freeze
+  end
+
+  class System < Resource
+    def time = ServerTime.from(@client.request('GET', '/v1/time'))
+  end
+
+  module Pagination
+    module_function
+
+    def each(fetch, filters, max_pages: 100, &block)
+      raise ArgumentError, 'max_pages must be a positive integer' unless max_pages.is_a?(Integer) && max_pages.positive?
+
+      filters = filters.dup
+      cursor = filters[:cursor]
+      max_pages.times do
+        page = fetch.call(**filters)
+        page.items.each(&block)
+        next_cursor = page.next_cursor
+        return if next_cursor.nil? || next_cursor.to_s.empty?
+        raise Error, 'Paymos API returned the same pagination cursor twice' if next_cursor == cursor
+
+        cursor = next_cursor
+        filters[:cursor] = cursor
+      end
+    end
+  end
+end

data/lib/paymos/errors.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Paymos
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class SignatureMismatchError < Error; end
+  class TimestampSkewError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body, :headers, :problem
+
+    def initialize(status, body, headers = {})
+      @status = status
+      @body = body.to_s
+      @headers = headers.to_h.transform_keys { |key| key.to_s.downcase }
+      @problem = parse_problem(@body)
+      super("Paymos API #{status}: #{detail}")
+    end
+
+    def errors
+      value = problem.is_a?(Hash) ? problem['errors'] : nil
+      value.is_a?(Array) ? value : []
+    end
+
+    def code
+      first = errors.first
+      value = first.is_a?(Hash) ? first['code'] : problem&.fetch('code', nil)
+      value.to_s
+    end
+
+    def field
+      first = errors.first
+      first.is_a?(Hash) ? first['field'] : problem&.fetch('field', nil)
+    end
+
+    def detail
+      value = problem&.fetch('detail', nil)
+      first = errors.first
+      value ||= first['message'] if first.is_a?(Hash)
+      value ||= code unless code.empty?
+      value ||= problem&.fetch('title', nil)
+      value ||= body unless body.empty?
+      value || 'empty response'
+    end
+
+    def retry_after_seconds(now: Time.now)
+      value = headers['retry-after']
+      return nil if value.nil? || value.empty?
+      return value.to_i if value.match?(/\A\d+\z/)
+
+      [(Time.httpdate(value) - now).ceil, 0].max
+    rescue ArgumentError
+      nil
+    end
+
+    private
+
+    def parse_problem(value)
+      parsed = value.empty? ? nil : JSON.parse(value)
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  class ValidationError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class NotFoundError < ApiError; end
+  class ConflictError < ApiError; end
+  class GoneError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+  class UnavailableError < ServerError; end
+
+  ERROR_TYPES = {
+    400 => ValidationError,
+    401 => AuthenticationError,
+    403 => AuthenticationError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    410 => GoneError,
+    429 => RateLimitError,
+    503 => UnavailableError
+  }.freeze
+
+  def self.api_error(status, body, headers = {})
+    type = ERROR_TYPES.fetch(status, status >= 500 ? ServerError : ApiError)
+    type.new(status, body, headers)
+  end
+end

data/lib/paymos/models.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Paymos
+  module InvoiceStatus
+    AWAITING_CLIENT = 'awaiting_client'
+    AWAITING_PAYMENT = 'awaiting_payment'
+    CONFIRMING = 'confirming'
+    UNDERPAID_WAITING = 'underpaid_waiting'
+    PAID = 'paid'
+    PAID_OVER = 'paid_over'
+    UNDERPAID = 'underpaid'
+    EXPIRED = 'expired'
+    CANCELLED = 'cancelled'
+  end
+
+  module WithdrawalStatus
+    CREATED = 'created'
+    PENDING_REVIEW = 'pending_review'
+    SIGNED = 'signed'
+    CANCELLING = 'cancelling'
+    COMPLETED = 'completed'
+    FAILED = 'failed'
+    CANCELLED = 'cancelled'
+  end
+
+  class Model
+    class << self
+      attr_reader :field_names, :required_names
+
+      def fields(*names, required: names)
+        @field_names = names.freeze
+        @required_names = required.freeze
+        attr_reader(*names)
+      end
+
+      def from(value)
+        raise Error, 'Paymos API response must be a JSON object' unless value.is_a?(Hash)
+
+        attributes = field_names.to_h { |name| [name, value[name.to_s]] }
+        missing = required_names.select { |name| attributes[name].nil? }
+        raise Error, "Paymos API response is missing: #{missing.join(', ')}" unless missing.empty?
+
+        new(**attributes)
+      end
+    end
+
+    def initialize(**attributes)
+      unknown = attributes.keys - self.class.field_names
+      raise ArgumentError, "Unknown model fields: #{unknown.join(', ')}" unless unknown.empty?
+
+      self.class.field_names.each do |name|
+        instance_variable_set("@#{name}", Model.deep_freeze(attributes[name]))
+      end
+      freeze
+    end
+
+    def [](name)
+      public_send(name.to_sym)
+    end
+
+    def to_h
+      self.class.field_names.to_h { |name| [name, public_send(name)] }
+    end
+
+    def self.deep_freeze(value)
+      case value
+      when Hash
+        value.transform_values { |item| deep_freeze(item) }.freeze
+      when Array
+        value.map { |item| deep_freeze(item) }.freeze
+      else
+        value.freeze
+      end
+    end
+  end
+
+  class Order < Model
+    fields :external_id, :client_id, :amount, :currency, :network,
+           required: %i[external_id amount currency]
+  end
+
+  class Transfer < Model
+    fields :tx_hash, :amount, :status, :created_at, :confirmed_at,
+           :required_confirmations, :estimated_confirmation_at, :explorer_url,
+           required: %i[tx_hash amount status created_at]
+  end
+
+  class Payment < Model
+    fields :currency, :network, :chain_id, :contract_address, :expected, :address,
+           :exchange_rate, :paid, :remaining, :fee, :net, :transfers,
+           required: %i[currency network chain_id expected]
+
+    def self.from(value)
+      model = super
+      transfers = model.transfers&.map { |item| Transfer.from(item) }
+      new(**model.to_h, transfers: transfers)
+    end
+  end
+
+  class Invoice < Model
+    fields :invoice_id, :project_id, :status, :is_final, :is_test, :payment_url,
+           :order, :payment, :created_at, :updated_at, :expires_at, :completed_at,
+           required: %i[invoice_id project_id status is_final is_test payment_url order created_at updated_at]
+
+    def self.from(value)
+      model = super
+      new(**model.to_h, order: Order.from(model.order), payment: model.payment && Payment.from(model.payment))
+    end
+  end
+
+  class InvoiceListItem < Model
+    fields :invoice_id, :project_id, :external_order_id, :client_id, :status,
+           :is_final, :is_test, :amount, :currency, :network, :created_at,
+           :expires_at, :completed_at,
+           required: %i[invoice_id project_id external_order_id status is_final is_test amount currency created_at]
+  end
+
+  class Withdrawal < Model
+    fields :withdrawal_id, :external_order_id, :status, :is_final, :is_test,
+           :amount, :fee, :currency, :network, :destination_address, :tx_hash,
+           :explorer_url, :created_at, :completed_at, :failed_at, :cancelled_at,
+           required: %i[withdrawal_id external_order_id status is_final is_test amount currency
+                        network destination_address created_at]
+  end
+
+  class Balance < Model
+    fields :currency, :available
+  end
+
+  class ServerTime < Model
+    fields :server_time
+  end
+
+  class Page < Model
+    fields :items, :next_cursor, required: [:items]
+
+    def self.from(value, item_type:)
+      model = super(value)
+      raise Error, 'Paymos API page items must be an array' unless model.items.is_a?(Array)
+
+      new(items: model.items.map { |item| item_type.from(item) }, next_cursor: model.next_cursor)
+    end
+  end
+
+  class WebhookEvent < Model
+    fields :event_id, :event_type, :version, :occurred_at, :data
+
+    def self.from(value)
+      model = super
+      valid = model.event_id.is_a?(String) && !model.event_id.empty? &&
+              model.event_type.is_a?(String) && !model.event_type.empty? &&
+              model.version.is_a?(Integer) && model.version.positive? &&
+              model.occurred_at.is_a?(Integer) && model.occurred_at >= 0 &&
+              model.data.is_a?(Hash)
+      raise Error, 'Webhook event envelope is invalid' unless valid
+
+      model
+    end
+  end
+end

data/lib/paymos/signing.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'digest'
+require 'openssl'
+
+module Paymos
+  module Signing
+    module_function
+
+    def string_to_sign(timestamp, method, path, query = '', body = '')
+      body_hash = body.empty? ? '' : Digest::SHA256.hexdigest(body.encode(Encoding::UTF_8))
+      [timestamp, method.to_s.upcase, path, query, body_hash].join("\n")
+    end
+
+    def sign(secret, value)
+      Base64.strict_encode64(OpenSSL::HMAC.digest('SHA256', secret, value))
+    end
+
+    def authorization(api_key, api_secret, timestamp, method, path, query = '', body = '')
+      signature = sign(api_secret, string_to_sign(timestamp, method, path, query, body))
+      "HMAC-SHA256 #{api_key}:#{signature}"
+    end
+
+    def path_segment(value)
+      percent_encode(value)
+    end
+
+    def query(filters)
+      parts = filters.keys.sort_by(&:to_s).flat_map do |key|
+        raw = filters[key]
+        next [] if raw.nil?
+
+        values = raw.is_a?(Array) ? raw.sort_by(&:to_s) : [raw]
+        raise ArgumentError, "Paymos list filter cannot be empty: #{key}" if values.empty?
+
+        values.map do |value|
+          raise ArgumentError, "Invalid Paymos list filter: #{key}" unless value.is_a?(String) || value.is_a?(Integer)
+          raise ArgumentError, "Invalid Paymos list filter: #{key}" if value.to_s.empty?
+
+          "#{percent_encode(key)}=#{percent_encode(value)}"
+        end
+      end
+      parts.empty? ? '' : "?#{parts.join('&')}"
+    end
+
+    def percent_encode(value)
+      value.to_s.encode(Encoding::UTF_8).bytes.map do |byte|
+        character = byte.chr
+        character.match?(/[A-Za-z0-9._~-]/) ? character : format('%%%02X', byte)
+      end.join
+    end
+  end
+end

data/lib/paymos/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Paymos
+  VERSION = '1.0.0'
+end

data/lib/paymos/webhook_verifier.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+require 'time'
+
+module Paymos
+  class WebhookVerifier
+    def initialize(secret, tolerance: 300, clock: -> { Time.now.to_i })
+      unless secret.is_a?(String) && !secret.strip.empty?
+        raise ArgumentError,
+              'Webhook secret must be a non-empty string'
+      end
+      raise ArgumentError, 'Webhook tolerance must be non-negative' unless tolerance.is_a?(Integer) && tolerance >= 0
+
+      @secret = secret
+      @tolerance = tolerance
+      @clock = clock
+    end
+
+    def verify(signature_header, raw_body, now: nil)
+      assert_valid(signature_header, raw_body, now: now)
+      true
+    rescue SignatureMismatchError, TimestampSkewError
+      false
+    end
+
+    def assert_valid(signature_header, raw_body, now: nil)
+      raise ArgumentError, 'Raw webhook body must be a string' unless raw_body.is_a?(String)
+
+      timestamp, signatures = parse_header(signature_header)
+      current = now.nil? ? @clock.call.to_i : now.to_i
+      if (current - timestamp).abs > @tolerance
+        raise TimestampSkewError,
+              'Webhook timestamp is outside the allowed tolerance'
+      end
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', @secret, "#{timestamp}.#{raw_body}")
+      valid = signatures.any? { |value| secure_compare(expected, value.downcase) }
+      raise SignatureMismatchError, 'Webhook signature does not match payload' unless valid
+
+      nil
+    end
+
+    def construct_event(signature_header, raw_body, now: nil)
+      assert_valid(signature_header, raw_body, now: now)
+      WebhookEvent.from(JSON.parse(raw_body))
+    rescue JSON::ParserError => e
+      raise Error, "Webhook payload is invalid JSON: #{e.message}"
+    end
+
+    private
+
+    def parse_header(header)
+      timestamp = nil
+      signatures = []
+      header.to_s.split(',').each do |part|
+        key, value = part.strip.split('=', 2)
+        if key == 't'
+          unless timestamp.nil? && value&.match?(/\A\d+\z/)
+            raise SignatureMismatchError,
+                  'Webhook signature header is missing or malformed'
+          end
+
+          timestamp = value.to_i
+        end
+        signatures << value if key == 'v1' && !value.to_s.empty?
+      end
+      if timestamp.nil? || signatures.empty?
+        raise SignatureMismatchError,
+              'Webhook signature header is missing or malformed'
+      end
+
+      [timestamp, signatures]
+    end
+
+    def secure_compare(expected, actual)
+      return false unless expected.bytesize == actual.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, actual)
+    end
+  end
+end

data/lib/paymos.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'paymos/version'
+require_relative 'paymos/errors'
+require_relative 'paymos/models'
+require_relative 'paymos/signing'
+require_relative 'paymos/webhook_verifier'
+require_relative 'paymos/client'

data/sig/paymos.rbs

@@ -0,0 +1,202 @@
+module Paymos
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class SignatureMismatchError < Error
+  end
+
+  class TimestampSkewError < Error
+  end
+
+  class ApiError < Error
+    attr_reader status: Integer
+    attr_reader body: String
+    attr_reader headers: Hash[String, String]
+    attr_reader problem: Hash[String, untyped]?
+
+    def initialize: (Integer status, String body, ?Hash[untyped, untyped] headers) -> void
+    def errors: () -> Array[Hash[String, untyped]]
+    def code: () -> String
+    def field: () -> untyped
+    def detail: () -> String
+    def retry_after_seconds: (?now: Time) -> Integer?
+  end
+
+  class ValidationError < ApiError
+  end
+  class AuthenticationError < ApiError
+  end
+  class NotFoundError < ApiError
+  end
+  class ConflictError < ApiError
+  end
+  class GoneError < ApiError
+  end
+  class RateLimitError < ApiError
+  end
+  class ServerError < ApiError
+  end
+  class UnavailableError < ServerError
+  end
+
+  class Model
+    def []: (String | Symbol name) -> untyped
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Order < Model
+    attr_reader external_id: String
+    attr_reader client_id: String?
+    attr_reader amount: String
+    attr_reader currency: String
+    attr_reader network: String?
+  end
+
+  class Transfer < Model
+    attr_reader tx_hash: String
+    attr_reader amount: String
+    attr_reader status: String
+    attr_reader created_at: Integer
+    attr_reader confirmed_at: Integer?
+    attr_reader required_confirmations: Integer?
+    attr_reader estimated_confirmation_at: Integer?
+    attr_reader explorer_url: String?
+  end
+
+  class Payment < Model
+    attr_reader currency: String
+    attr_reader network: String
+    attr_reader chain_id: Integer
+    attr_reader contract_address: String?
+    attr_reader expected: String
+    attr_reader address: String?
+    attr_reader exchange_rate: String?
+    attr_reader paid: String?
+    attr_reader remaining: String?
+    attr_reader fee: String?
+    attr_reader net: String?
+    attr_reader transfers: Array[Transfer]?
+  end
+
+  class Invoice < Model
+    attr_reader invoice_id: String
+    attr_reader project_id: String
+    attr_reader status: String
+    attr_reader is_final: bool
+    attr_reader is_test: bool
+    attr_reader payment_url: String
+    attr_reader order: Order
+    attr_reader payment: Payment?
+    attr_reader created_at: Integer
+    attr_reader updated_at: Integer
+    attr_reader expires_at: Integer?
+    attr_reader completed_at: Integer?
+  end
+
+  class InvoiceListItem < Model
+    attr_reader invoice_id: String
+    attr_reader project_id: String
+    attr_reader external_order_id: String
+    attr_reader client_id: String?
+    attr_reader status: String
+    attr_reader is_final: bool
+    attr_reader is_test: bool
+    attr_reader amount: String
+    attr_reader currency: String
+    attr_reader network: String?
+    attr_reader created_at: Integer
+    attr_reader expires_at: Integer?
+    attr_reader completed_at: Integer?
+  end
+
+  class Withdrawal < Model
+    attr_reader withdrawal_id: String
+    attr_reader external_order_id: String
+    attr_reader status: String
+    attr_reader is_final: bool
+    attr_reader is_test: bool
+    attr_reader amount: String
+    attr_reader fee: String?
+    attr_reader currency: String
+    attr_reader network: String
+    attr_reader destination_address: String
+    attr_reader tx_hash: String?
+    attr_reader explorer_url: String?
+    attr_reader created_at: Integer
+    attr_reader completed_at: Integer?
+    attr_reader failed_at: Integer?
+    attr_reader cancelled_at: Integer?
+  end
+
+  class Balance < Model
+    attr_reader currency: String
+    attr_reader available: String
+  end
+
+  class ServerTime < Model
+    attr_reader server_time: Integer
+  end
+
+  class Page[Item] < Model
+    attr_reader items: Array[Item]
+    attr_reader next_cursor: String?
+  end
+
+  class WebhookEvent[Data] < Model
+    attr_reader event_id: String
+    attr_reader event_type: String
+    attr_reader version: Integer
+    attr_reader occurred_at: Integer
+    attr_reader data: Data
+  end
+
+  class Invoices
+    def create: (project_id: String, amount: String, currency: String, external_order_id: String, ?network: String?, ?allow_multiple_payments: bool?, ?customer_fee_percent: Integer?, ?client_id: String?) -> Invoice
+    def get: (String invoice_id) -> Invoice
+    def list: (?limit: Integer?, ?cursor: String?, ?status: String | Array[String]?, ?external_order_id: String?, ?project_id: String?, ?created_from: Integer?, ?created_to: Integer?) -> Page[InvoiceListItem]
+    def cancel: (String invoice_id, reason: String) -> Invoice
+    def confirm_payment: (String invoice_id, currency: String, network: String) -> Invoice
+    def simulate_payment: (String invoice_id, stage: String) -> Invoice
+    def each: (?max_pages: Integer, **untyped filters) { (InvoiceListItem) -> void } -> void
+         | (?max_pages: Integer, **untyped filters) -> Enumerator[InvoiceListItem, void]
+  end
+
+  class Withdrawals
+    def create: (destination_address: String, network: String, currency: String, amount: String, external_order_id: String) -> Withdrawal
+    def get: (String withdrawal_id) -> Withdrawal
+    def list: (?limit: Integer?, ?cursor: String?, ?status: String | Array[String]?, ?external_order_id: String?, ?created_from: Integer?, ?created_to: Integer?) -> Page[Withdrawal]
+    def cancel: (String withdrawal_id, reason: String) -> Withdrawal
+    def simulate_completion: (String withdrawal_id) -> Withdrawal
+    def each: (?max_pages: Integer, **untyped filters) { (Withdrawal) -> void } -> void
+         | (?max_pages: Integer, **untyped filters) -> Enumerator[Withdrawal, void]
+  end
+
+  class Balances
+    def get: () -> Array[Balance]
+  end
+
+  class System
+    def time: () -> ServerTime
+  end
+
+  class Client
+    attr_reader invoices: Invoices
+    attr_reader withdrawals: Withdrawals
+    attr_reader balances: Balances
+    attr_reader system: System
+
+    def initialize: (api_key: String, api_secret: String, ?base_url: String, ?timeout: Numeric, ?max_retries: Integer, ?base_delay: Numeric, ?transport: untyped, ?clock: untyped, ?sleeper: untyped, ?random: Random) -> void
+  end
+
+  class WebhookVerifier
+    def initialize: (String secret, ?tolerance: Integer, ?clock: untyped) -> void
+    def verify: (String signature_header, String raw_body, ?now: Integer?) -> bool
+    def assert_valid: (String signature_header, String raw_body, ?now: Integer?) -> void
+    def construct_event: (String signature_header, String raw_body, ?now: Integer?) -> WebhookEvent[Hash[String, untyped]]
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: paymos
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Paymos Labs
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: HMAC-authenticated client for invoices, withdrawals, balances, and webhooks.
+email:
+- support@paymos.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/paymos.rb
+- lib/paymos/client.rb
+- lib/paymos/errors.rb
+- lib/paymos/models.rb
+- lib/paymos/signing.rb
+- lib/paymos/version.rb
+- lib/paymos/webhook_verifier.rb
+- sig/paymos.rbs
+homepage: https://paymos.io/docs/server-sdks
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Paymos-labs/ruby-sdk
+  changelog_uri: https://github.com/Paymos-labs/ruby-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://paymos.io/docs/server-sdks
+  homepage_uri: https://paymos.io/docs/server-sdks
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby SDK for the Paymos Merchant API
+test_files: []