paymos 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c747bf5230f29f3a2dbed376f50af76f02c05b65b9a89558190dace7f76971dc
-  data.tar.gz: 6f26d4b9c429dd3d09d9f9c4edda6772bd8fd9b4fa77eb184188de10d831c61e
+  metadata.gz: 49ac8a8d2ef52cb2e7b6bcfe98000a10f9dd01d5a3f2d5aee34dad4cbf9ff96f
+  data.tar.gz: 3d4e5c92f6a16ff27a3c44194f47366972d4a107de0f1547a75cabb1cca55a60
 SHA512:
-  metadata.gz: 865bc2412c06f86d0f152bf2767308a2fcb06cf7386f253bd2467d509a1fb8609c1a16aa3130c85600e1c57302d1c7d598bc05c8f8d7907b289b93a0dd540153
-  data.tar.gz: 9ecf3a0cce176412d201d3ec956731b1924f9b4c0ec188d5d0717e9a39367a24beac7031c74e0678cd887513443791d73aaae9c918929094b044196e723ce552
+  metadata.gz: 1db9fc7682ffbc870ea487f7012f4088e56b5c11eab2884254ae05fd17abc378cc54c507e2ac9e427c051b3ff8867a63327b5dbb41ff93214fe9751226605689
+  data.tar.gz: 371e65ded8041b3ed73b0688da5058fa09f08d42d3e91c51b5554cd166b6bc4738e27238e0c397d14b7fe0c0a063ecfd6e2c5bfd6092c1be2b15a6edfca0f593

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [1.5.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.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

data/README.md

@@ -1,6 +1,6 @@
 # Paymos Ruby SDK
 
-Official Ruby client for the Paymos Merchant API — invoices, withdrawals, balances,
+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).
 
@@ -32,6 +32,44 @@ 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:
 

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, :payment_channels, :payment_channel_deposits
+    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,
@@ -43,6 +43,7 @@ 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)
@@ -296,6 +297,53 @@ 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.

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
@@ -127,6 +132,14 @@ 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

data/lib/paymos/version.rb

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

data/sig/paymos.rbs

@@ -133,6 +133,35 @@ 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?
@@ -245,6 +274,15 @@ 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
@@ -272,6 +310,7 @@ 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

metadata

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