paymos 1.1.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 170d4a77262048eb627400e9019deb92e25d0c6d3e73a49d5e477cc432a00baf
-  data.tar.gz: bb92e9a4e584630a22271c93512ad094ec7cd5b47921c90ed9df19e0780fee3e
+  metadata.gz: 53529447a1b6190b8df0810a738fe95a68dbfcbb40bfc00eb0884bd57b191992
+  data.tar.gz: b94adfdafc75ba8e72e799dbd5df529c9926802553c7e2f17910a56fff4fa68b
 SHA512:
-  metadata.gz: '084533c7bcc70a3eb7b1a50b8b2ca3e6617d2de251a19b8c9a04e6a4e8d9817898c21c1587977111afbb86ddcedc464d348d1739cb2d40fd01d023c01c00d528'
-  data.tar.gz: 0a7d4bfc9102170947b98c356c3b97df9ec405056854d1040676024e0fd7371d8a0115975087a1171f3324e73a1ed533e0a3f50a82761783e57a630a609417db
+  metadata.gz: 8d4261c76165f99433e7d2711f46e990136ab7d009d0d4ddc84e82bacd72d5470c963212a9fc7bc3acde0ffb3b295f89afb2401739c1c890c35f2b8e651147b8
+  data.tar.gz: 460c55e0c00c9c0ccafb66ad7b2f13beaaefd3f3797daab6a65a9c46f662e031c542f98ec8ba476e660fabe2839f42eb0ab8cb68e59c332f0b63fd21412b4236

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.4.0] - 2026-10-30
+
+- fix(plugins): reject invalid Woo refund controls and unblock SDK checks
+- fix(sdk): preserve current refund contracts in TON conformance
+- fix(ton): return friendly addresses with existing webhook schema
+- feat(sdk-ruby): add refund create, list and get
+
+- **403 is no longer reported as an authentication failure.** `Paymos::PermissionError` (subclasses `Paymos::AuthenticationError`, so existing `rescue` blocks keep working) now carries every 403.
+- **Base URL must use HTTPS.** Plain HTTP is accepted only against a loopback host, which is what a local integration test points at. The API secret signs every request, so a plaintext base URL put that credential on the wire.
+
+## [1.3.0] - 2026-10-14
+
+- Make the SDK CI tier green
+- Fix invoice-late-payment audit findings (tasks 4.1-4.8)
+- feat(invoices): accept full late payments without reopening invoices
+- fix(sdk-conformance): восемь копий контракта разошлись с каноном — 403 снова permission
+- fix(sdk): HTTPS обязателен, а 403 перестал притворяться ошибкой ключа
+
+- **403 is no longer reported as an authentication failure.** `Paymos::PermissionError` (subclasses `Paymos::AuthenticationError`, so existing `rescue` blocks keep working) now carries every 403.
+- **Base URL must use HTTPS.** Plain HTTP is accepted only against a loopback host, which is what a local integration test points at. The API secret signs every request, so a plaintext base URL put that credential on the wire.
+
+## [1.2.0] - 2026-08-28
+
+- release: the changelog rot had a cause, and it was not the one I named
+- audit: the shipped plugin and SDK docs described a product we stopped shipping
+- docs(sdk): the READMEs say static wallets, not payment channels
+- feat(sdk): payment-channel webhooks and the flow in every README
+- feat(ruby-sdk): payment channels, and a feed reader that cannot stop early
+- feat(sdk-conformance): declare the payment-channel operations
+- docs(api): pin the empty-body signing rule and fix the published POST vector
+
 ## [1.1.1] - 2026-08-02
 
 - fix(ecosystem): recover SDK releases

data/README.md

@@ -1,6 +1,7 @@
 # Paymos Ruby SDK
 
-Official Ruby client for the Paymos Merchant API. Its only runtime dependency is
+Official Ruby client for the Paymos Merchant API — invoices, withdrawals, refunds, balances,
+and static per-customer wallets with their confirmed-deposit feed. Its only runtime dependency is
 Ruby's official `base64` gem (required separately by modern Ruby versions).
 
 ```bash
@@ -31,6 +32,74 @@ Responses are immutable Ruby objects with documented RBS signatures; request
 keywords remain idiomatic `snake_case` and are converted directly to the Paymos
 wire contract.
 
+Create invoice refunds with a Payment key. The server calculates the amount and
+returns it as a decimal string; there are no amount or destination arguments:
+
+```ruby
+refund = paymos.refunds.create(
+  invoice_id: invoice.invoice_id,
+  mode: Paymos::RefundMode::OVERPAYMENT,
+  external_order_id: "refund_order_123_overpayment"
+)
+puts "#{refund.withdrawal_id}: #{refund.amount} #{refund.currency}"
+
+filters = {
+  invoice_id: invoice.invoice_id,
+  status: [Paymos::WithdrawalStatus::COMPLETED],
+  created_from: "2026-01-01T00:00:00Z",
+  created_to: "2027-01-01T00:00:00Z",
+  limit: 100
+}
+page = paymos.refunds.list(**filters)
+next_page = paymos.refunds.list(**filters, cursor: page.next_cursor) if page.next_cursor
+refund = paymos.refunds.get(refund.withdrawal_id)
+```
+
+`full` returns all remaining payment; `overpayment` returns all remaining excess.
+For a payment of 120 against an invoice of 100, these are initially 120 and 20.
+After the overpayment refund completes, a new full refund returns 100. Refunds
+and their pages are immutable, including their decimal strings and first sender.
+
+Keep the same invoice, mode and `external_order_id` when retrying an uncertain
+outcome. Creation returns 201 and an identical replay returns 200; both yield a
+`Paymos::Refund`. Changing the mode under the same key raises
+`Paymos::ConflictError` (409). Missing or foreign refund IDs raise
+`Paymos::NotFoundError` (404). List periods use RFC 3339 timestamps, and
+`paymos.refunds.each` provides the same bounded cursor iteration as invoices.
+In sandbox, use `paymos.withdrawals.simulate_completion(refund.withdrawal_id)`,
+then read the refund again. Refunds have their own list and do not appear in the
+ordinary withdrawals list.
+
+A payment channel is one payer's reusable set of deposit addresses. Create it,
+read its rails, then poll the confirmed-deposit feed and persist the cursor:
+
+```ruby
+channel = paymos.payment_channels.create(project_id: "prj_...", external_id: "customer_42")
+channel.networks.each do |rail|
+  next if rail.address.nil? # this rail has not provisioned yet
+
+  puts "#{rail.network} #{rail.status} #{rail.address}"
+end
+
+feed = paymos.payment_channel_deposits.read(cursor: saved_cursor, limit: 100)
+feed.items.each { |deposit| credit(deposit) }
+save_cursor(feed.next_cursor)
+```
+
+Four things that bite a caller who guesses. Repeating the same `external_id`
+returns the **same** channel — `200` instead of `201`, and both bodies are a
+channel, so calling this on every checkout is safe: a repeat is not a duplicate
+and not an error. A rail's `address` is nil until that rail finishes
+provisioning and never changes once set, so nil means "not yet", not "no
+address". A nil `minimum_deposit` means "we cannot quote a minimum right now",
+never "there is no minimum" — reading it as zero is how a merchant accepts a
+deposit that lands below the live minimum and is never credited. And
+`next_cursor` is never empty, not even on a page with no items: store it and
+resume from it, and never loop until it is nil the way `each` ends a list,
+because that loop either spins forever or stops on the first quiet page and
+leaves reconciliation silently behind. `confirmed_from` is the first poll's
+lower bound only; afterwards the stored cursor is the resume mechanism.
+
 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.
@@ -40,9 +109,48 @@ 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)
+  .construct_event(request.env.fetch("HTTP_X_WEBHOOK_SIGNATURE"), request.body.read)
+```
+
+Every `payment_channel.deposit.*` event carries a full payment-channel deposit as its
+`data`; `data` comes back as a plain Hash, so hand it to `PaymentChannelDeposit.from`
+to get the same typed model the deposit feed returns:
+
+```ruby
+case event.event_type
+when "payment_channel.deposit.confirmed"
+  deposit = Paymos::PaymentChannelDeposit.from(event.data)
+  credit(deposit.payment_channel_external_id, deposit.net) if deposit.is_final
+end
 ```
 
+`confirming` and `reorged` are advisory and may arrive out of order — a `confirming`
+can land after the `confirmed` for the same deposit, and a `reorged` can be superseded
+by a later `confirmed`. Credit only on `payment_channel.deposit.confirmed` with
+`is_final` true, and never let an advisory event regress a deposit you already know is
+confirmed: crediting on `confirming` releases goods against money a reorg can still
+take back.
+
 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.
+
+## 401 and 403 are different problems
+
+A **401** means the credential is absent, malformed or unverifiable — fix the key or the signing
+clock, and stop retrying.
+
+A **403** means the credential was accepted and something else refused. It covers two very
+different situations:
+
+- **the key is wrong for this call** — `payout_key_required`, `payment_key_required`,
+  `forbidden`;
+- **the key is fine, the account or project state says no** — `whitelist_required`,
+  `merchant_suspended`, `widget_inactive`, `terminal_not_enabled`, `not_sandbox`.
+
+A customer entering a payout address that is not whitelisted yet is the second kind: nothing is
+wrong with your credentials, and paging the on-call engineer about them is the wrong move. Always
+switch on the error `code` before deciding what to do.
+
+`Paymos::PermissionError` subclasses `Paymos::AuthenticationError`, so a `rescue` written before
+this split keeps catching 403.

data/lib/paymos/client.rb

@@ -19,7 +19,7 @@ module Paymos
   class Client
     SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
 
-    attr_reader :invoices, :withdrawals, :balances, :system
+    attr_reader :invoices, :withdrawals, :refunds, :balances, :system, :payment_channels, :payment_channel_deposits
 
     def initialize(api_key:, api_secret:, base_url: 'https://api.paymos.io', timeout: 30,
                    max_retries: 2, base_delay: 0.150, transport: nil,
@@ -29,16 +29,10 @@ module Paymos
         raise ConfigurationError,
               'timeout, max_retries, and base_delay are invalid'
       end
-      raise ConfigurationError, 'base_url is required' if base_url.to_s.strip.empty?
+      validate_base_url(base_url)
 
       @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
@@ -49,6 +43,9 @@ module Paymos
       @random = random
       @invoices = Invoices.new(self)
       @withdrawals = Withdrawals.new(self)
+      @refunds = Refunds.new(self)
+      @payment_channels = PaymentChannels.new(self)
+      @payment_channel_deposits = PaymentChannelDeposits.new(self)
       @balances = Balances.new(self)
       @system = System.new(self)
     end
@@ -104,6 +101,24 @@ module Paymos
 
     private
 
+    # The API secret signs every request, so the scheme decides whether that credential is
+    # readable in transit. HTTPS in production; plain HTTP only against a loopback host, which
+    # is what a local integration test points at. Mirrors the Rust SDK's validate_base_url.
+    def validate_base_url(base_url)
+      raise ConfigurationError, 'base_url is required' if base_url.to_s.strip.empty?
+
+      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
+
+      loopback = %w[localhost 127.0.0.1 ::1].include?(origin.host.to_s.downcase)
+      return if origin.scheme == 'https' || (origin.scheme == 'http' && loopback)
+
+      raise ConfigurationError, 'base_url must use HTTPS (HTTP is allowed only for loopback tests)'
+    end
+
     def default_transport(method, url, headers, body, timeout)
       uri = URI(url)
       request_type = Net::HTTP.const_get(method.capitalize)
@@ -228,7 +243,7 @@ module Paymos
     end
 
     def simulate_payment(invoice_id, stage:)
-      raise ArgumentError, 'Invalid simulation stage' unless %w[paid overpaid underpay cancel].include?(stage)
+      raise ArgumentError, 'Invalid simulation stage' unless %w[paid overpaid underpay cancel paid_late].include?(stage)
 
       Invoice.from(@client.request('POST', "/v1/sandbox/invoices/#{segment(invoice_id)}/simulate-payment",
                                    payload: { stage: }))
@@ -282,6 +297,127 @@ module Paymos
     end
   end
 
+  class Refunds < Resource
+    def create(invoice_id:, mode:, external_order_id:)
+      values = { invoice_id:, mode:, 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?
+      raise ArgumentError, 'Invalid refund mode' unless [RefundMode::FULL, RefundMode::OVERPAYMENT].include?(mode)
+
+      Refund.from(@client.request('POST', '/v1/refunds', payload: values))
+    end
+
+    def simulate(refund_id, status)
+      Refund.from(@client.request('POST', "/v1/sandbox/refunds/#{segment(refund_id)}/simulate",
+                                  payload: { status: }))
+    end
+
+    def get(refund_id) = Refund.from(@client.request('GET', "/v1/refunds/#{segment(refund_id)}"))
+
+    def list(limit: nil, cursor: nil, invoice_id: nil, status: nil, created_from: nil, created_to: nil)
+      filters = validate_list_filters({ limit:, cursor:, invoice_id:, status: }.compact)
+      validate_period(created_from, created_to)
+      filters.merge!({ created_from:, created_to: }.compact)
+      Page.from(@client.request('GET', '/v1/refunds', query: Signing.query(filters)), item_type: Refund)
+    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 validate_period(created_from, created_to)
+      from, to = [created_from, created_to].map do |value|
+        next if value.nil?
+
+        unless value.is_a?(String) &&
+               value.match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/i)
+          raise ArgumentError, 'created_from and created_to must be RFC 3339 timestamps'
+        end
+
+        Time.iso8601(value)
+      end
+      raise ArgumentError, 'created_to must be later than created_from' if from && to && from >= to
+    end
+  end
+
+  class PaymentChannels < Resource
+    # Create — or fetch. The same project plus external id answers 200 with the channel that already
+    # exists instead of 201 with a duplicate; both are a channel, so a caller never reads the status.
+    def create(project_id:, external_id:)
+      values = { project_id:, external_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?
+
+      PaymentChannel.from(@client.request('POST', '/v1/payment-channels', payload: values))
+    end
+
+    def get(payment_channel_id)
+      PaymentChannel.from(@client.request('GET', "/v1/payment-channels/#{segment(payment_channel_id)}"))
+    end
+
+    def list(limit: nil, cursor: nil, status: nil, external_id: nil, project_id: nil)
+      filters = validate_list_filters({ limit:, cursor:, status:, external_id:, project_id: }.compact)
+      Page.from(@client.request('GET', '/v1/payment-channels', query: Signing.query(filters)),
+                item_type: PaymentChannel)
+    end
+
+    def block(payment_channel_id)
+      PaymentChannel.from(@client.request('POST', "/v1/payment-channels/#{segment(payment_channel_id)}/block"))
+    end
+
+    def unblock(payment_channel_id)
+      PaymentChannel.from(@client.request('POST', "/v1/payment-channels/#{segment(payment_channel_id)}/unblock"))
+    end
+
+    # Sandbox only. network is required; stage defaults to confirmed server-side and is omitted from
+    # the payload entirely when unset, never sent as null.
+    def simulate_deposit(payment_channel_id, amount:, currency:, network:, stage: nil)
+      values = { amount:, currency:, network: }
+      missing = values.select { |_name, value| !value.is_a?(String) || value.strip.empty? }.keys
+      raise ArgumentError, "Required values are missing: #{missing.join(', ')}" unless missing.empty?
+
+      unless stage.nil? || %w[confirming reorged confirmed].include?(stage)
+        raise ArgumentError, 'Invalid simulation stage'
+      end
+
+      path = "/v1/sandbox/payment-channels/#{segment(payment_channel_id)}/simulate-deposit"
+      payload = { amount:, currency:, network:, stage: }.compact
+      PaymentChannelDeposit.from(@client.request('POST', path, payload:))
+    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 PaymentChannelDeposits < Resource
+    def get(deposit_id)
+      PaymentChannelDeposit.from(@client.request('GET', "/v1/payment-channel-deposits/#{segment(deposit_id)}"))
+    end
+
+    # Reads ONE page of the confirmed-deposit feed. Deliberately not named list and deliberately
+    # without an iterator: the feed never ends, so a helper that loops until the cursor is empty would
+    # either spin forever or stop on the first quiet page and leave reconciliation silently behind.
+    # confirmed_from is the initial-sync lower bound only; afterwards resume from the stored cursor.
+    def read(limit: nil, cursor: nil, project_id: nil, payment_channel_id: nil, confirmed_from: nil)
+      unless confirmed_from.nil? || (confirmed_from.is_a?(Integer) && confirmed_from >= 0)
+        raise ArgumentError, 'confirmed_from must be non-negative Unix seconds'
+      end
+
+      filters = validate_list_filters({ limit:, cursor:, project_id:, payment_channel_id:,
+                                        confirmed_from: }.compact)
+      PaymentChannelDepositFeedPage.from(
+        @client.request('GET', '/v1/payment-channel-deposits', query: Signing.query(filters))
+      )
+    end
+  end
+
   class Balances < Resource
     def get = Array(@client.request('GET', '/v1/balances')).map { |item| Balance.from(item) }.freeze
   end

data/lib/paymos/errors.rb

@@ -69,6 +69,15 @@ module Paymos
 
   class ValidationError < ApiError; end
   class AuthenticationError < ApiError; end
+
+  # A 403: the credential was accepted, something else refused. Deliberately a SUBCLASS of
+  # AuthenticationError so existing rescue blocks keep working, and deliberately its own class
+  # because the remedy is usually not "fix the key": 403 carries wrong-key-type
+  # (payout_key_required, payment_key_required, forbidden) next to plain business
+  # state (whitelist_required, merchant_suspended, widget_inactive, terminal_not_enabled,
+  # not_sandbox). An unwhitelisted payout address reported as an authentication failure sends the
+  # on-call engineer to rotate perfectly good credentials. Switch on `code` for the remedy.
+  class PermissionError < AuthenticationError; end
   class NotFoundError < ApiError; end
   class ConflictError < ApiError; end
   class GoneError < ApiError; end
@@ -79,7 +88,7 @@ module Paymos
   ERROR_TYPES = {
     400 => ValidationError,
     401 => AuthenticationError,
-    403 => AuthenticationError,
+    403 => PermissionError,
     404 => NotFoundError,
     409 => ConflictError,
     410 => GoneError,

data/lib/paymos/models.rb

@@ -23,6 +23,11 @@ module Paymos
     CANCELLED = 'cancelled'
   end
 
+  module RefundMode
+    FULL = 'full'
+    OVERPAYMENT = 'overpayment'
+  end
+
   class Model
     class << self
       attr_reader :field_names, :required_names
@@ -98,8 +103,11 @@ module Paymos
   end
 
   class Invoice < Model
+    # paid_late_at: invoice-late-payment — money crossed the invoice's total after it had already
+    # closed as expired/underpaid. Unix seconds; nil while there is no late mark (field omitted).
+    # status keeps its terminal meaning; the marker travels beside it.
     fields :invoice_id, :project_id, :status, :is_final, :is_test, :payment_url,
-           :order, :payment, :created_at, :updated_at, :expires_at, :completed_at,
+           :order, :payment, :created_at, :updated_at, :expires_at, :completed_at, :paid_late_at,
            required: %i[invoice_id project_id status is_final is_test payment_url order created_at updated_at]
 
     def self.from(value)
@@ -109,9 +117,10 @@ module Paymos
   end
 
   class InvoiceListItem < Model
+    # paid_late_at: invoice-late-payment additive late mark, Unix seconds; nil while there is no mark (field omitted).
     fields :invoice_id, :project_id, :external_order_id, :client_id, :status,
            :is_final, :is_test, :amount, :currency, :network, :created_at,
-           :expires_at, :completed_at,
+           :expires_at, :completed_at, :paid_late_at,
            required: %i[invoice_id project_id external_order_id status is_final is_test amount currency created_at]
   end
 
@@ -123,6 +132,88 @@ module Paymos
                         network destination_address created_at]
   end
 
+  class Refund < Model
+    fields :withdrawal_id, :invoice_id, :mode, :external_order_id, :status, :is_final, :is_test,
+           :amount, :fee, :currency, :network, :destination_address, :first_sender, :tx_hash,
+           :explorer_url, :created_at, :completed_at, :failed_at, :cancelled_at, :type, :project_id,
+           required: %i[withdrawal_id invoice_id mode external_order_id status is_final is_test amount
+                        currency network destination_address first_sender created_at]
+  end
+
+  # One accepted token on one rail. A missing minimum_deposit means the rail cannot be quoted right
+  # now — it never means the token has no minimum.
+  class PaymentChannelToken < Model
+    fields :symbol, :minimum_deposit, required: %i[symbol]
+  end
+
+  # One rail of a channel. The address is absent until that rail provisions, and never changes after.
+  class PaymentChannelNetwork < Model
+    fields :network, :status, :address, :tokens, required: %i[network status tokens]
+
+    def self.from(value)
+      model = super
+      new(**model.to_h, tokens: model.tokens.map { |item| PaymentChannelToken.from(item) })
+    end
+  end
+
+  class PaymentChannel < Model
+    fields :id, :project_id, :external_id, :status, :is_accepting_payments, :is_fully_provisioned,
+           :is_test, :applied_fee_percent, :customer_fee_percent, :networks, :created_at, :updated_at,
+           required: %i[id project_id external_id status is_accepting_payments is_fully_provisioned
+                        is_test applied_fee_percent customer_fee_percent networks created_at updated_at]
+
+    def self.from(value)
+      model = super
+      new(**model.to_h, networks: model.networks.map { |item| PaymentChannelNetwork.from(item) })
+    end
+  end
+
+  # Doubles as the `data` payload of every payment_channel.deposit.* webhook event (decoded via
+  # WebhookVerifier#construct_event, then PaymentChannelDeposit.from(event.data)). `confirming` and
+  # `reorged` are ADVISORY and may arrive out of order — a `confirming` can land after the
+  # `confirmed` for the same deposit, and a `reorged` can be superseded by a later `confirmed`.
+  # Credit only on payment_channel.deposit.confirmed with is_final true, and never let an advisory
+  # event regress a deposit already known to be confirmed: crediting on `confirming` releases goods
+  # against money a reorg can still take back.
+  class PaymentChannelDeposit < Model
+    fields :id, :payment_channel_id, :project_id, :payment_channel_external_id, :status, :is_final,
+           :is_test, :currency, :network, :chain_id, :contract_address, :gross, :fee, :net,
+           :applied_fee_percent, :customer_fee_percent, :tx_hash, :transfer_id, :source_address,
+           :destination_address, :block_height, :first_included_block_timestamp, :explorer_url,
+           :created_at, :updated_at, :confirmed_at,
+           required: %i[id payment_channel_id project_id payment_channel_external_id status is_final
+                        is_test currency network chain_id gross fee net applied_fee_percent
+                        customer_fee_percent tx_hash transfer_id destination_address block_height
+                        created_at updated_at]
+  end
+
+  # The one feed position that could not be rendered, and why. Without it a stuck feed is
+  # byte-identical to a quiet day, and a merchant cannot tell "no new payments" from "I am not
+  # seeing my money". Reasons: booked_auth_missing, inconsistent, deposit_missing, channel_missing,
+  # transfer_missing, not_confirmed.
+  class PaymentChannelDepositFeedBlockage < Model
+    fields :deposit_id, :reason
+  end
+
+  # One page of the confirmed-deposit feed. Deliberately NOT a Page: next_cursor is required here,
+  # because the feed has no last page. An empty page still hands back a cursor past the global
+  # publication positions this merchant's filter skipped, so store it and resume from it — never
+  # stop polling because a page came back empty.
+  class PaymentChannelDepositFeedPage < Model
+    fields :items, :next_cursor, :blocked, required: %i[items next_cursor]
+
+    def self.from(value)
+      model = super
+      raise Error, 'Paymos API page items must be an array' unless model.items.is_a?(Array)
+
+      cursor = model.next_cursor
+      raise Error, 'Paymos deposit feed page is missing a cursor' unless cursor.is_a?(String) && !cursor.empty?
+
+      new(items: model.items.map { |item| PaymentChannelDeposit.from(item) }, next_cursor: cursor,
+          blocked: model.blocked && PaymentChannelDepositFeedBlockage.from(model.blocked))
+    end
+  end
+
   class Balance < Model
     fields :currency, :available
   end

data/lib/paymos/version.rb

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

data/sig/paymos.rbs

@@ -133,6 +133,104 @@ module Paymos
     attr_reader cancelled_at: Integer?
   end
 
+  module RefundMode
+    FULL: "full"
+    OVERPAYMENT: "overpayment"
+  end
+
+  class Refund < Model
+    attr_reader withdrawal_id: String
+    attr_reader invoice_id: String
+    attr_reader mode: "full" | "overpayment"
+    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 first_sender: String
+    attr_reader type: String?
+    attr_reader project_id: 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 PaymentChannelToken < Model
+    attr_reader symbol: String
+    attr_reader minimum_deposit: String?
+  end
+
+  class PaymentChannelNetwork < Model
+    attr_reader network: String
+    attr_reader status: String
+    attr_reader address: String?
+    attr_reader tokens: Array[PaymentChannelToken]
+  end
+
+  class PaymentChannel < Model
+    attr_reader id: String
+    attr_reader project_id: String
+    attr_reader external_id: String
+    attr_reader status: String
+    attr_reader is_accepting_payments: bool
+    attr_reader is_fully_provisioned: bool
+    attr_reader is_test: bool
+    attr_reader applied_fee_percent: Numeric
+    attr_reader customer_fee_percent: Integer
+    attr_reader networks: Array[PaymentChannelNetwork]
+    attr_reader created_at: Integer
+    attr_reader updated_at: Integer
+  end
+
+  class PaymentChannelDeposit < Model
+    attr_reader id: String
+    attr_reader payment_channel_id: String
+    attr_reader project_id: String
+    attr_reader payment_channel_external_id: String
+    attr_reader status: String
+    attr_reader is_final: bool
+    attr_reader is_test: bool
+    attr_reader currency: String
+    attr_reader network: String
+    attr_reader chain_id: Integer
+    attr_reader contract_address: String?
+    attr_reader gross: String
+    attr_reader fee: String
+    attr_reader net: String
+    attr_reader applied_fee_percent: Numeric
+    attr_reader customer_fee_percent: Integer
+    attr_reader tx_hash: String
+    attr_reader transfer_id: String
+    attr_reader source_address: String?
+    attr_reader destination_address: String
+    attr_reader block_height: Integer
+    attr_reader first_included_block_timestamp: Integer?
+    attr_reader explorer_url: String?
+    attr_reader created_at: Integer
+    attr_reader updated_at: Integer
+    attr_reader confirmed_at: Integer?
+  end
+
+  class PaymentChannelDepositFeedBlockage < Model
+    attr_reader deposit_id: String
+    attr_reader reason: String
+  end
+
+  # next_cursor is NOT optional: the feed never ends, so an empty page still carries the cursor to
+  # resume from. Store it; never stop because a page came back empty.
+  class PaymentChannelDepositFeedPage < Model
+    attr_reader items: Array[PaymentChannelDeposit]
+    attr_reader next_cursor: String
+    attr_reader blocked: PaymentChannelDepositFeedBlockage?
+  end
+
   class Balance < Model
     attr_reader currency: String
     attr_reader available: String
@@ -176,6 +274,31 @@ module Paymos
          | (?max_pages: Integer, **untyped filters) -> Enumerator[Withdrawal, void]
   end
 
+  class Refunds
+    def simulate: (String refund_id, String status) -> Refund
+    def create: (invoice_id: String, mode: "full" | "overpayment", external_order_id: String) -> Refund
+    def get: (String refund_id) -> Refund
+    def list: (?limit: Integer?, ?cursor: String?, ?invoice_id: String?, ?status: String | Array[String]?, ?created_from: String?, ?created_to: String?) -> Page[Refund]
+    def each: (?max_pages: Integer, **untyped filters) { (Refund) -> void } -> void
+         | (?max_pages: Integer, **untyped filters) -> Enumerator[Refund, void]
+  end
+
+  class PaymentChannels
+    def create: (project_id: String, external_id: String) -> PaymentChannel
+    def get: (String payment_channel_id) -> PaymentChannel
+    def list: (?limit: Integer?, ?cursor: String?, ?status: String | Array[String]?, ?external_id: String?, ?project_id: String?) -> Page[PaymentChannel]
+    def block: (String payment_channel_id) -> PaymentChannel
+    def unblock: (String payment_channel_id) -> PaymentChannel
+    def simulate_deposit: (String payment_channel_id, amount: String, currency: String, network: String, ?stage: String?) -> PaymentChannelDeposit
+    def each: (?max_pages: Integer, **untyped filters) { (PaymentChannel) -> void } -> void
+         | (?max_pages: Integer, **untyped filters) -> Enumerator[PaymentChannel, void]
+  end
+
+  class PaymentChannelDeposits
+    def get: (String deposit_id) -> PaymentChannelDeposit
+    def read: (?limit: Integer?, ?cursor: String?, ?project_id: String?, ?payment_channel_id: String?, ?confirmed_from: Integer?) -> PaymentChannelDepositFeedPage
+  end
+
   class Balances
     def get: () -> Array[Balance]
   end
@@ -187,6 +310,9 @@ module Paymos
   class Client
     attr_reader invoices: Invoices
     attr_reader withdrawals: Withdrawals
+    attr_reader refunds: Refunds
+    attr_reader payment_channels: PaymentChannels
+    attr_reader payment_channel_deposits: PaymentChannelDeposits
     attr_reader balances: Balances
     attr_reader system: System
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paymos
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Paymos Labs