billingio 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be246a686bc1dac9b2c0bf75a6f66c5f77b58ba205ad72628a09d72a57d4a9e0
+  data.tar.gz: 610719813172e602cc3b78c4f5b21120d91320a34945fc483c6ecc9743a4f8af
+SHA512:
+  metadata.gz: dfce4a65d73b3c03f3a968fe376c4b6ca47d22fa5f693c8134672b94c09972872109b00b5abd3047d22a84f27b7acbb57fbc26860d1f100411cc03cd37b241a3
+  data.tar.gz: a47bdd1a11a97832bb68bb3d0c17baa6f45b6259430106a3e859b7266b39bf75238541c61995f01c6f700b1ddc25ca9cdb1c7e880dcf407d93d39a403cc3c6f5

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "minitest", "~> 5.0"
+  gem "rake", "~> 13.0"
+  gem "rubocop", "~> 1.0", require: false
+  gem "webmock", "~> 3.0"
+end

data/README.md

@@ -0,0 +1,267 @@
+# billingio
+
+Official Ruby SDK for the [billing.io](https://billing.io) crypto checkout API.
+
+- Create payment checkouts settled in USDT / USDC on Tron or Arbitrum
+- Manage webhook endpoints and verify signatures
+- Query event history with cursor-based pagination
+- Zero runtime dependencies (stdlib only)
+
+## Requirements
+
+- Ruby >= 3.0
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "billingio"
+```
+
+Then run:
+
+```
+bundle install
+```
+
+Or install directly:
+
+```
+gem install billingio
+```
+
+## Quickstart
+
+```ruby
+require "billingio"
+
+client = BillingIO::Client.new(api_key: "sk_live_...")
+
+# Create a checkout
+checkout = client.checkouts.create(
+  amount_usd: 49.99,
+  chain:      "tron",
+  token:      "USDT",
+  metadata:   { "order_id" => "ord_12345" }
+)
+
+puts checkout.checkout_id     # => "co_..."
+puts checkout.deposit_address # => "T..."
+puts checkout.status          # => "pending"
+
+# Poll for status updates
+status = client.checkouts.get_status(checkout.checkout_id)
+puts status.confirmations            # => 0
+puts status.required_confirmations   # => 19
+puts status.polling_interval_ms      # => 2000
+```
+
+## Checkouts
+
+```ruby
+# Create with idempotency key
+checkout = client.checkouts.create(
+  amount_usd:      100.00,
+  chain:           "arbitrum",
+  token:           "USDC",
+  idempotency_key: SecureRandom.uuid
+)
+
+# Retrieve a checkout
+checkout = client.checkouts.get("co_abc123")
+
+# Get lightweight status for polling
+status = client.checkouts.get_status("co_abc123")
+
+# List checkouts with optional status filter
+list = client.checkouts.list(status: "confirmed", limit: 10)
+list.each { |c| puts c.checkout_id }
+```
+
+## Webhook Endpoints
+
+```ruby
+# Create a webhook endpoint
+endpoint = client.webhooks.create(
+  url:         "https://example.com/webhooks/billing",
+  events:      ["checkout.completed", "checkout.expired"],
+  description: "Production webhook"
+)
+
+# IMPORTANT: Store the secret securely -- it is only returned on creation.
+puts endpoint.secret  # => "whsec_..."
+
+# List all endpoints
+endpoints = client.webhooks.list
+endpoints.each { |ep| puts "#{ep.webhook_id}: #{ep.url}" }
+
+# Retrieve a single endpoint
+endpoint = client.webhooks.get("we_abc123")
+
+# Delete an endpoint
+client.webhooks.delete("we_abc123")
+```
+
+## Webhook Signature Verification
+
+When receiving webhook events, always verify the signature before processing.
+
+### Rails
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    payload = request.body.read
+    header  = request.headers["X-Billing-Signature"]
+    secret  = ENV.fetch("BILLING_WEBHOOK_SECRET")
+
+    begin
+      event = BillingIO::WebhookSignature.verify(
+        payload:   payload,
+        header:    header,
+        secret:    secret,
+        tolerance: 300
+      )
+    rescue BillingIO::WebhookVerificationError => e
+      return head :bad_request
+    end
+
+    case event["type"]
+    when "checkout.completed"
+      # Fulfill the order
+      order = Order.find_by!(billing_checkout_id: event["checkout_id"])
+      order.fulfill!
+    when "checkout.expired"
+      # Handle expiration
+    end
+
+    head :ok
+  end
+end
+```
+
+### Sinatra
+
+```ruby
+require "sinatra"
+require "billingio"
+
+post "/webhooks/billing" do
+  payload = request.body.read
+  header  = request.env["HTTP_X_BILLING_SIGNATURE"]
+  secret  = ENV.fetch("BILLING_WEBHOOK_SECRET")
+
+  begin
+    event = BillingIO::WebhookSignature.verify(
+      payload: payload,
+      header:  header,
+      secret:  secret
+    )
+  rescue BillingIO::WebhookVerificationError
+    halt 400, "Invalid signature"
+  end
+
+  case event["type"]
+  when "checkout.completed"
+    # Handle successful payment
+  end
+
+  status 200
+  body "ok"
+end
+```
+
+## Events
+
+```ruby
+# List events with filters
+events = client.events.list(
+  type:        "checkout.completed",
+  checkout_id: "co_abc123",
+  limit:       50
+)
+
+events.each do |event|
+  puts "#{event.event_id}: #{event.type} at #{event.created_at}"
+  puts "  checkout: #{event.data.checkout_id}" # nested Checkout model
+end
+
+# Retrieve a single event
+event = client.events.get("evt_abc123")
+```
+
+## Pagination
+
+All list endpoints return a `BillingIO::PaginatedList` with cursor-based
+pagination. Use `has_more?` and `next_cursor` to page through results.
+
+```ruby
+# Manual pagination
+cursor = nil
+
+loop do
+  page = client.checkouts.list(cursor: cursor, limit: 100)
+
+  page.each do |checkout|
+    puts checkout.checkout_id
+  end
+
+  break unless page.has_more?
+  cursor = page.next_cursor
+end
+```
+
+`PaginatedList` includes `Enumerable`, so you can use `map`, `select`,
+`first`, and other enumeration methods on each page.
+
+## Health Check
+
+```ruby
+health = client.health.get
+puts health.status   # => "healthy"
+puts health.version  # => "1.0.0"
+```
+
+## Error Handling
+
+All API errors raise `BillingIO::Error` with structured details.
+
+```ruby
+begin
+  client.checkouts.get("co_nonexistent")
+rescue BillingIO::Error => e
+  puts e.message      # => "No checkout found with ID co_nonexistent."
+  puts e.type         # => "not_found"
+  puts e.code         # => "checkout_not_found"
+  puts e.status_code  # => 404
+  puts e.param        # => "checkout_id"
+end
+```
+
+Error types (from the API):
+
+| Type                    | Description                            |
+|-------------------------|----------------------------------------|
+| `invalid_request`       | Missing or invalid parameters          |
+| `authentication_error`  | Invalid or missing API key             |
+| `not_found`             | Resource does not exist                |
+| `idempotency_conflict`  | Idempotency key reused with diff params|
+| `rate_limited`          | Too many requests                      |
+| `internal_error`        | Server-side error                      |
+
+## Configuration
+
+```ruby
+# Override the base URL (e.g. for local development)
+client = BillingIO::Client.new(
+  api_key:  "sk_test_...",
+  base_url: "http://localhost:8080/v1"
+)
+```
+
+## License
+
+MIT

data/billingio.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/billingio/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "billingio"
+  spec.version       = BillingIO::VERSION
+  spec.authors       = ["billing.io"]
+  spec.email         = ["support@billing.io"]
+
+  spec.summary       = "Ruby SDK for the billing.io crypto checkout API"
+  spec.description   = "Official Ruby client for billing.io -- non-custodial crypto " \
+                        "payment checkouts with stablecoin settlement. Create checkouts, " \
+                        "manage webhooks, verify signatures, and query event history."
+  spec.homepage      = "https://github.com/billingio/billingio-ruby"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "homepage_uri"      => spec.homepage,
+    "source_code_uri"   => "https://github.com/billingio/billingio-ruby",
+    "changelog_uri"     => "https://github.com/billingio/billingio-ruby/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://docs.billing.io",
+    "bug_tracker_uri"   => "https://github.com/billingio/billingio-ruby/issues"
+  }
+
+  spec.files = Dir["lib/**/*.rb"] + ["billingio.gemspec", "Gemfile", "README.md"]
+  spec.require_paths = ["lib"]
+
+  # Zero runtime dependencies -- stdlib only (net/http, openssl, json, cgi).
+end

data/lib/billingio/client.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Main entry point for the billing.io API.
+  #
+  # @example
+  #   client = BillingIO::Client.new(api_key: "sk_live_...")
+  #   checkout = client.checkouts.create(
+  #     amount_usd: 49.99,
+  #     chain:      "tron",
+  #     token:      "USDT"
+  #   )
+  class Client
+    DEFAULT_BASE_URL = "https://api.billing.io/v1"
+
+    # @param api_key  [String] your secret API key (sk_live_... or sk_test_...)
+    # @param base_url [String] API root URL (override for testing or local dev)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @http = HttpClient.new(api_key: api_key, base_url: base_url)
+    end
+
+    # @return [BillingIO::Checkouts]
+    def checkouts
+      @checkouts ||= Checkouts.new(@http)
+    end
+
+    # @return [BillingIO::Webhooks]
+    def webhooks
+      @webhooks ||= Webhooks.new(@http)
+    end
+
+    # @return [BillingIO::Events]
+    def events
+      @events ||= Events.new(@http)
+    end
+
+    # @return [BillingIO::Health]
+    def health
+      @health ||= Health.new(@http)
+    end
+  end
+end

data/lib/billingio/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Raised when the billing.io API returns a non-2xx response.
+  #
+  # Attributes correspond to the error envelope documented in the API spec:
+  #   { "error": { "type", "code", "message", "param" } }
+  class Error < StandardError
+    attr_reader :type, :code, :status_code, :param
+
+    # @param message      [String]       human-readable error description
+    # @param type         [String, nil]  error category (e.g. "invalid_request")
+    # @param code         [String, nil]  machine-readable code (e.g. "missing_required_field")
+    # @param status_code  [Integer, nil] HTTP status code
+    # @param param        [String, nil]  request parameter that triggered the error
+    def initialize(message = nil, type: nil, code: nil, status_code: nil, param: nil)
+      @type        = type
+      @code        = code
+      @status_code = status_code
+      @param       = param
+      super(message)
+    end
+
+    # Build an Error from the parsed JSON error envelope and HTTP status.
+    #
+    # @param body        [Hash]    parsed response body
+    # @param status_code [Integer] HTTP status code
+    # @return [BillingIO::Error]
+    def self.from_response(body, status_code)
+      err = body["error"] || {}
+      new(
+        err["message"] || "Unknown error (HTTP #{status_code})",
+        type:        err["type"],
+        code:        err["code"],
+        status_code: status_code,
+        param:       err["param"]
+      )
+    end
+  end
+
+  # Raised when webhook signature verification fails.
+  class WebhookVerificationError < StandardError; end
+end

data/lib/billingio/http_client.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module BillingIO
+  # @api private
+  #
+  # Thin wrapper around Net::HTTP that handles authentication,
+  # JSON serialization, and error mapping.  Every public resource
+  # class delegates its HTTP work here.
+  class HttpClient
+    # @param api_key  [String] bearer token (sk_live_... / sk_test_...)
+    # @param base_url [String] API root including version path
+    def initialize(api_key:, base_url:)
+      @api_key  = api_key
+      @base_url = base_url.chomp("/")
+    end
+
+    # ---- HTTP verbs -------------------------------------------------------
+
+    def get(path, params = {})
+      uri = build_uri(path, params)
+      request = Net::HTTP::Get.new(uri)
+      execute(uri, request)
+    end
+
+    def post(path, body = nil, headers = {})
+      uri = build_uri(path)
+      request = Net::HTTP::Post.new(uri)
+      if body
+        request.body = JSON.generate(body)
+        request["Content-Type"] = "application/json"
+      end
+      headers.each { |k, v| request[k] = v }
+      execute(uri, request)
+    end
+
+    def delete(path)
+      uri = build_uri(path)
+      request = Net::HTTP::Delete.new(uri)
+      execute(uri, request)
+    end
+
+    private
+
+    def build_uri(path, params = {})
+      uri = URI("#{@base_url}#{path}")
+      unless params.empty?
+        query = params.reject { |_, v| v.nil? }
+                      .map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }
+                      .join("&")
+        uri.query = query unless query.empty?
+      end
+      uri
+    end
+
+    def execute(uri, request)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"]        = "application/json"
+      request["User-Agent"]    = "billingio-ruby/#{BillingIO::VERSION}"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 30
+      http.read_timeout = 60
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+
+      # 204 No Content -- nothing to parse
+      return nil if status == 204
+
+      body = parse_body(response)
+
+      if status >= 200 && status < 300
+        body
+      else
+        raise Error.from_response(body.is_a?(Hash) ? body : {}, status)
+      end
+    end
+
+    def parse_body(response)
+      return {} if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      { "error" => { "message" => response.body } }
+    end
+  end
+end

data/lib/billingio/models/checkout.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a payment checkout.
+  #
+  # @attr_reader checkout_id            [String]      unique identifier (prefixed +co_+)
+  # @attr_reader deposit_address        [String]      blockchain address to send funds to
+  # @attr_reader chain                  [String]      blockchain network ("tron" | "arbitrum")
+  # @attr_reader token                  [String]      stablecoin token ("USDT" | "USDC")
+  # @attr_reader amount_usd             [Float]       original USD amount
+  # @attr_reader amount_atomic          [String]      token amount in smallest unit
+  # @attr_reader status                 [String]      current checkout status
+  # @attr_reader tx_hash                [String, nil] on-chain transaction hash
+  # @attr_reader confirmations          [Integer]     current confirmation count
+  # @attr_reader required_confirmations [Integer]     confirmations needed
+  # @attr_reader expires_at             [String]      ISO-8601 expiry timestamp
+  # @attr_reader detected_at            [String, nil] ISO-8601 detection timestamp
+  # @attr_reader confirmed_at           [String, nil] ISO-8601 confirmation timestamp
+  # @attr_reader created_at             [String]      ISO-8601 creation timestamp
+  # @attr_reader metadata               [Hash, nil]   arbitrary key-value pairs
+  class Checkout
+    ATTRS = %i[
+      checkout_id deposit_address chain token
+      amount_usd amount_atomic status tx_hash
+      confirmations required_confirmations
+      expires_at detected_at confirmed_at created_at
+      metadata
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Checkout]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Checkout checkout_id=#{@checkout_id.inspect} status=#{@status.inspect} amount_usd=#{@amount_usd.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/checkout_status.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Lightweight status response returned by the polling endpoint.
+  #
+  # @attr_reader checkout_id            [String]      checkout identifier
+  # @attr_reader status                 [String]      current status
+  # @attr_reader tx_hash                [String, nil] on-chain transaction hash
+  # @attr_reader confirmations          [Integer]     current confirmation count
+  # @attr_reader required_confirmations [Integer]     confirmations needed
+  # @attr_reader detected_at            [String, nil] ISO-8601 detection timestamp
+  # @attr_reader confirmed_at           [String, nil] ISO-8601 confirmation timestamp
+  # @attr_reader polling_interval_ms    [Integer]     suggested polling interval
+  class CheckoutStatus
+    ATTRS = %i[
+      checkout_id status tx_hash
+      confirmations required_confirmations
+      detected_at confirmed_at polling_interval_ms
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::CheckoutStatus]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::CheckoutStatus checkout_id=#{@checkout_id.inspect} status=#{@status.inspect} confirmations=#{@confirmations.inspect}/#{@required_confirmations.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a webhook event.
+  #
+  # @attr_reader event_id    [String]           unique identifier (prefixed +evt_+)
+  # @attr_reader type        [String]           event type (e.g. "checkout.completed")
+  # @attr_reader checkout_id [String]           related checkout identifier
+  # @attr_reader data        [BillingIO::Checkout] checkout snapshot at time of event
+  # @attr_reader created_at  [String]           ISO-8601 creation timestamp
+  class Event
+    ATTRS = %i[event_id type checkout_id data created_at].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+
+        # Wrap the nested checkout data in a Checkout model
+        if attr == :data && value.is_a?(Hash)
+          value = Checkout.from_hash(value)
+        end
+
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Event]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        val = instance_variable_get(:"@#{attr}")
+        h[attr.to_s] = val.respond_to?(:to_h) && val.is_a?(Checkout) ? val.to_h : val
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Event event_id=#{@event_id.inspect} type=#{@type.inspect} checkout_id=#{@checkout_id.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/health_response.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents the API health check response.
+  #
+  # @attr_reader status  [String] service health ("healthy")
+  # @attr_reader version [String] API version (e.g. "1.0.0")
+  class HealthResponse
+    ATTRS = %i[status version].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::HealthResponse]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::HealthResponse status=#{@status.inspect} version=#{@version.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/paginated_list.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Generic cursor-paginated list returned by all list endpoints.
+  #
+  # @attr_reader data        [Array]        items on the current page
+  # @attr_reader has_more    [Boolean]      whether more pages exist
+  # @attr_reader next_cursor [String, nil]  opaque cursor for the next page
+  class PaginatedList
+    include Enumerable
+
+    attr_reader :data, :has_more, :next_cursor
+
+    # @param data        [Array]        deserialized model instances
+    # @param has_more    [Boolean]      pagination flag
+    # @param next_cursor [String, nil]  cursor for fetching the next page
+    def initialize(data:, has_more:, next_cursor:)
+      @data        = data
+      @has_more    = has_more
+      @next_cursor = next_cursor
+    end
+
+    # Iterate over items on the current page.
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # Number of items on the current page.
+    def size
+      @data.size
+    end
+    alias_method :length, :size
+
+    # @return [Boolean]
+    def has_more?
+      @has_more
+    end
+
+    # Build a PaginatedList from a raw API response hash.
+    #
+    # @param hash      [Hash]  raw response body with "data", "has_more", "next_cursor"
+    # @param model_cls [Class] model class that responds to +.from_hash+
+    # @return [BillingIO::PaginatedList]
+    def self.from_hash(hash, model_cls)
+      items = (hash["data"] || []).map { |item| model_cls.from_hash(item) }
+      new(
+        data:        items,
+        has_more:    hash["has_more"] || false,
+        next_cursor: hash["next_cursor"]
+      )
+    end
+
+    def inspect
+      "#<BillingIO::PaginatedList size=#{size} has_more=#{@has_more.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/webhook_endpoint.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a registered webhook endpoint.
+  #
+  # @attr_reader webhook_id  [String]            unique identifier (prefixed +we_+)
+  # @attr_reader url         [String]            HTTPS endpoint receiving events
+  # @attr_reader events      [Array<String>]     subscribed event types
+  # @attr_reader secret      [String, nil]       HMAC signing secret (only on creation)
+  # @attr_reader description [String, nil]       human-readable label
+  # @attr_reader status      [String]            "active" or "disabled"
+  # @attr_reader created_at  [String]            ISO-8601 creation timestamp
+  class WebhookEndpoint
+    ATTRS = %i[
+      webhook_id url events secret
+      description status created_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::WebhookEndpoint]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::WebhookEndpoint webhook_id=#{@webhook_id.inspect} url=#{@url.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/resources/checkouts.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to checkout-related API endpoints.
+  #
+  #   client.checkouts.create(amount_usd: 49.99, chain: "tron", token: "USDT")
+  #   client.checkouts.list(status: "pending")
+  #   client.checkouts.get("co_abc123")
+  #   client.checkouts.get_status("co_abc123")
+  class Checkouts
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Create a new payment checkout.
+    #
+    # @param amount_usd          [Numeric]      amount in USD (>= 0.01)
+    # @param chain               [String]       blockchain network ("tron" | "arbitrum")
+    # @param token               [String]       stablecoin token ("USDT" | "USDC")
+    # @param expires_in_seconds  [Integer]      checkout TTL in seconds (300..86400, default 1800)
+    # @param metadata            [Hash, nil]    arbitrary key-value pairs (max 20 keys)
+    # @param idempotency_key     [String, nil]  UUID for idempotent requests
+    # @return [BillingIO::Checkout]
+    # @raise [BillingIO::Error]
+    def create(amount_usd:, chain:, token:, expires_in_seconds: 1800, metadata: nil, idempotency_key: nil)
+      body = {
+        "amount_usd"         => amount_usd,
+        "chain"              => chain,
+        "token"              => token,
+        "expires_in_seconds" => expires_in_seconds
+      }
+      body["metadata"] = metadata if metadata
+
+      headers = {}
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+      data = @http.post("/checkouts", body, headers)
+      Checkout.from_hash(data)
+    end
+
+    # List checkouts with cursor-based pagination.
+    #
+    # @param cursor [String, nil]  opaque cursor for the next page
+    # @param limit  [Integer]      items per page (1..100, default 25)
+    # @param status [String, nil]  filter by checkout status
+    # @return [BillingIO::PaginatedList<BillingIO::Checkout>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25, status: nil)
+      params = { limit: limit }
+      params[:cursor] = cursor if cursor
+      params[:status] = status if status
+
+      data = @http.get("/checkouts", params)
+      PaginatedList.from_hash(data, Checkout)
+    end
+
+    # Retrieve a single checkout by ID.
+    #
+    # @param checkout_id [String] checkout identifier (prefixed +co_+)
+    # @return [BillingIO::Checkout]
+    # @raise [BillingIO::Error]
+    def get(checkout_id)
+      data = @http.get("/checkouts/#{checkout_id}")
+      Checkout.from_hash(data)
+    end
+
+    # Retrieve lightweight status for polling.
+    #
+    # @param checkout_id [String] checkout identifier (prefixed +co_+)
+    # @return [BillingIO::CheckoutStatus]
+    # @raise [BillingIO::Error]
+    def get_status(checkout_id)
+      data = @http.get("/checkouts/#{checkout_id}/status")
+      CheckoutStatus.from_hash(data)
+    end
+  end
+end

data/lib/billingio/resources/events.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to the event history API.
+  #
+  #   client.events.list(type: "checkout.completed")
+  #   client.events.get("evt_abc123")
+  class Events
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # List events with cursor-based pagination.
+    #
+    # @param cursor      [String, nil] opaque cursor for the next page
+    # @param limit       [Integer]     items per page (1..100, default 25)
+    # @param type        [String, nil] filter by event type (e.g. "checkout.completed")
+    # @param checkout_id [String, nil] filter by related checkout
+    # @return [BillingIO::PaginatedList<BillingIO::Event>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25, type: nil, checkout_id: nil)
+      params = { limit: limit }
+      params[:cursor]      = cursor      if cursor
+      params[:type]        = type        if type
+      params[:checkout_id] = checkout_id if checkout_id
+
+      data = @http.get("/events", params)
+      PaginatedList.from_hash(data, Event)
+    end
+
+    # Retrieve a single event by ID.
+    #
+    # @param event_id [String] event identifier (prefixed +evt_+)
+    # @return [BillingIO::Event]
+    # @raise [BillingIO::Error]
+    def get(event_id)
+      data = @http.get("/events/#{event_id}")
+      Event.from_hash(data)
+    end
+  end
+end

data/lib/billingio/resources/health.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to the health check endpoint.
+  #
+  #   client.health.get
+  class Health
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Check API health.
+    #
+    # @return [BillingIO::HealthResponse]
+    # @raise [BillingIO::Error]
+    def get
+      data = @http.get("/health")
+      HealthResponse.from_hash(data)
+    end
+  end
+end

data/lib/billingio/resources/webhooks.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to webhook endpoint management.
+  #
+  #   client.webhooks.create(url: "https://example.com/hook", events: ["checkout.completed"])
+  #   client.webhooks.list
+  #   client.webhooks.get("we_abc123")
+  #   client.webhooks.delete("we_abc123")
+  class Webhooks
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Register a new webhook endpoint.
+    #
+    # @param url         [String]        HTTPS URL to receive events
+    # @param events      [Array<String>] event types to subscribe to
+    # @param description [String, nil]   human-readable label (max 256 chars)
+    # @return [BillingIO::WebhookEndpoint]  includes the +secret+ field (store it securely)
+    # @raise [BillingIO::Error]
+    def create(url:, events:, description: nil)
+      body = {
+        "url"    => url,
+        "events" => events
+      }
+      body["description"] = description if description
+
+      data = @http.post("/webhooks", body)
+      WebhookEndpoint.from_hash(data)
+    end
+
+    # List webhook endpoints with cursor-based pagination.
+    #
+    # @param cursor [String, nil] opaque cursor for the next page
+    # @param limit  [Integer]     items per page (1..100, default 25)
+    # @return [BillingIO::PaginatedList<BillingIO::WebhookEndpoint>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25)
+      params = { limit: limit }
+      params[:cursor] = cursor if cursor
+
+      data = @http.get("/webhooks", params)
+      PaginatedList.from_hash(data, WebhookEndpoint)
+    end
+
+    # Retrieve a single webhook endpoint by ID.
+    #
+    # @param webhook_id [String] webhook endpoint identifier (prefixed +we_+)
+    # @return [BillingIO::WebhookEndpoint]
+    # @raise [BillingIO::Error]
+    def get(webhook_id)
+      data = @http.get("/webhooks/#{webhook_id}")
+      WebhookEndpoint.from_hash(data)
+    end
+
+    # Delete a webhook endpoint.
+    #
+    # @param webhook_id [String] webhook endpoint identifier (prefixed +we_+)
+    # @return [nil]
+    # @raise [BillingIO::Error]
+    def delete(webhook_id)
+      @http.delete("/webhooks/#{webhook_id}")
+      nil
+    end
+  end
+end

data/lib/billingio/version.rb

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

data/lib/billingio/webhook.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Convenience module matching the public API contract:
+  #
+  #   BillingIO::Webhook.verify_signature(payload:, header:, secret:)
+  #
+  # Delegates to {BillingIO::WebhookSignature.verify}.
+  module Webhook
+    module_function
+
+    # Verify a webhook payload and return the parsed event Hash.
+    #
+    # @param payload   [String]  raw request body (unparsed JSON)
+    # @param header    [String]  value of the X-Billing-Signature header
+    # @param secret    [String]  webhook endpoint secret (whsec_...)
+    # @param tolerance [Integer] max age of the event in seconds (default 300)
+    # @return [Hash] the parsed webhook event
+    # @raise [BillingIO::WebhookVerificationError] on any verification failure
+    def verify_signature(payload:, header:, secret:, tolerance: WebhookSignature::DEFAULT_TOLERANCE)
+      WebhookSignature.verify(
+        payload:   payload,
+        header:    header,
+        secret:    secret,
+        tolerance: tolerance
+      )
+    end
+  end
+end

data/lib/billingio/webhook_signature.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module BillingIO
+  # Verifies webhook signatures sent by billing.io.
+  #
+  # The +X-Billing-Signature+ header has the format:
+  #   t={unix_timestamp},v1={hex_hmac_sha256}
+  #
+  # The signed payload is: "{timestamp}.{raw_body}"
+  module WebhookSignature
+    # Default tolerance window in seconds (5 minutes).
+    DEFAULT_TOLERANCE = 300
+
+    # Header name used by billing.io for the signature.
+    SIGNATURE_HEADER = "X-Billing-Signature"
+
+    module_function
+
+    # Verify a webhook payload and return the parsed event Hash.
+    #
+    # @param payload   [String]  raw request body (unparsed JSON)
+    # @param header    [String]  value of the X-Billing-Signature header
+    # @param secret    [String]  webhook endpoint secret (whsec_...)
+    # @param tolerance [Integer] max age of the event in seconds (default 300)
+    # @return [Hash] the parsed webhook event
+    # @raise [BillingIO::WebhookVerificationError] on any verification failure
+    def verify(payload:, header:, secret:, tolerance: DEFAULT_TOLERANCE)
+      raise WebhookVerificationError, "Missing signature header" if header.nil? || header.empty?
+      raise WebhookVerificationError, "Missing webhook secret"   if secret.nil? || secret.empty?
+
+      timestamp, signature = parse_header(header)
+
+      # Timestamp tolerance check
+      now = Time.now.to_i
+      if (now - timestamp).abs > tolerance
+        raise WebhookVerificationError,
+              "Timestamp outside tolerance. Event: #{timestamp}, now: #{now}, tolerance: #{tolerance}s"
+      end
+
+      # Compute expected HMAC-SHA256
+      signed_payload = "#{timestamp}.#{payload}"
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
+
+      unless secure_compare(expected, signature)
+        raise WebhookVerificationError, "Signature mismatch"
+      end
+
+      # Parse and return the event
+      begin
+        JSON.parse(payload)
+      rescue JSON::ParserError
+        raise WebhookVerificationError, "Invalid JSON in webhook body"
+      end
+    end
+
+    # Parse the "t=...,v1=..." header into [timestamp, signature].
+    #
+    # @param header [String]
+    # @return [Array(Integer, String)]
+    # @raise [BillingIO::WebhookVerificationError]
+    def parse_header(header)
+      parts = {}
+      header.split(",").each do |segment|
+        key, *rest = segment.split("=")
+        parts[key.strip] = rest.join("=").strip
+      end
+
+      timestamp = Integer(parts["t"], 10) rescue nil
+      signature = parts["v1"]
+
+      if timestamp.nil? || signature.nil? || signature.empty?
+        raise WebhookVerificationError,
+              "Invalid signature header format. Expected: t={timestamp},v1={signature}"
+      end
+
+      [timestamp, signature]
+    end
+
+    # Constant-time string comparison to prevent timing attacks.
+    # Uses OpenSSL.fixed_length_secure_compare (available Ruby 2.7+)
+    # with a fallback to a manual XOR-based comparison.
+    #
+    # @param a [String]
+    # @param b [String]
+    # @return [Boolean]
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      if OpenSSL.respond_to?(:fixed_length_secure_compare)
+        OpenSSL.fixed_length_secure_compare(a, b)
+      else
+        a_bytes = a.unpack("C*")
+        b_bytes = b.unpack("C*")
+
+        result = 0
+        a_bytes.each_with_index do |byte, i|
+          result |= byte ^ b_bytes[i]
+        end
+
+        result.zero?
+      end
+    end
+
+    private_class_method :parse_header, :secure_compare
+  end
+end

data/lib/billingio.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+require_relative "billingio/version"
+require_relative "billingio/errors"
+require_relative "billingio/http_client"
+require_relative "billingio/webhook_signature"
+require_relative "billingio/webhook"
+
+# Models
+require_relative "billingio/models/checkout"
+require_relative "billingio/models/checkout_status"
+require_relative "billingio/models/webhook_endpoint"
+require_relative "billingio/models/event"
+require_relative "billingio/models/health_response"
+require_relative "billingio/models/paginated_list"
+
+# Resources
+require_relative "billingio/resources/checkouts"
+require_relative "billingio/resources/webhooks"
+require_relative "billingio/resources/events"
+require_relative "billingio/resources/health"
+
+require_relative "billingio/client"

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: billingio
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- billing.io
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-01-30 00:00:00.000000000 Z
+dependencies: []
+description: Official Ruby client for billing.io -- non-custodial crypto payment checkouts
+  with stablecoin settlement. Create checkouts, manage webhooks, verify signatures,
+  and query event history.
+email:
+- support@billing.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- billingio.gemspec
+- lib/billingio.rb
+- lib/billingio/client.rb
+- lib/billingio/errors.rb
+- lib/billingio/http_client.rb
+- lib/billingio/models/checkout.rb
+- lib/billingio/models/checkout_status.rb
+- lib/billingio/models/event.rb
+- lib/billingio/models/health_response.rb
+- lib/billingio/models/paginated_list.rb
+- lib/billingio/models/webhook_endpoint.rb
+- lib/billingio/resources/checkouts.rb
+- lib/billingio/resources/events.rb
+- lib/billingio/resources/health.rb
+- lib/billingio/resources/webhooks.rb
+- lib/billingio/version.rb
+- lib/billingio/webhook.rb
+- lib/billingio/webhook_signature.rb
+homepage: https://github.com/billingio/billingio-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/billingio/billingio-ruby
+  source_code_uri: https://github.com/billingio/billingio-ruby
+  changelog_uri: https://github.com/billingio/billingio-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.billing.io
+  bug_tracker_uri: https://github.com/billingio/billingio-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.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for the billing.io crypto checkout API
+test_files: []