spree_cm_commissioner 2.13.4 → 2.13.7

data/app/services/spree_cm_commissioner/payment_fees/apply.rb

@@ -0,0 +1,30 @@
+module SpreeCmCommissioner
+  module PaymentFees
+    # Replaces the order's payment fee with what PaymentFees::Preview computes for
+    # `payment_method`, storing those exact amounts (same pattern as PricingModels::Activate):
+    # never recomputed through PaymentFeeRule#compute_amount, and closed so a later
+    # Adjustment#update! can't change them. Caller is expected to hold the transaction.
+    class Apply
+      prepend ::Spree::ServiceModule::Base
+
+      def call(order:, payment_method:)
+        order.adjustments.payment_fee.delete_all
+
+        preview = Preview.call(order: order, payment_method: payment_method).value[:payment_fee_preview]
+        preview.adjustments.each do |adjustment|
+          order.adjustments.create!(
+            amount: adjustment.amount,
+            source: adjustment.rule,
+            order: order,
+            label: adjustment.rule.label,
+            mandatory: true,
+            state: 'closed'
+          )
+        end
+
+        order.update_with_updater!
+        success(order: order, payment_fee_preview: preview)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/payment_fees/clear.rb

@@ -0,0 +1,15 @@
+module SpreeCmCommissioner
+  module PaymentFees
+    class Clear
+      prepend ::Spree::ServiceModule::Base
+
+      def call(order:)
+        return success(order: order) unless order.adjustments.payment_fee.exists?
+
+        order.adjustments.payment_fee.delete_all
+        order.update_with_updater!
+        success(order: order)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/payment_fees/preview.rb

@@ -0,0 +1,70 @@
+module SpreeCmCommissioner
+  module PaymentFees
+    # Computes, without persisting, the payment fee `payment_method` would add to `order`.
+    #
+    # The base is the gateway amount only (order total minus store credit, minus any payment fee
+    # already applied from an earlier attempt), since that's what the provider bills on. Line items
+    # resolve their own rule (product -> event -> vendor -> tenant/global); when they resolve to
+    # different rules, the gateway amount is split between rules by each group's share of line-item
+    # totals, and the leftover rounding cent goes to the last group so the bases always add up.
+    class Preview
+      prepend ::Spree::ServiceModule::Base
+
+      def call(order:, payment_method:)
+        gateway_amount = gateway_amount_for(order)
+        adjustments = build_adjustments(order, payment_method, gateway_amount)
+        amount = adjustments.sum(BigDecimal(0), &:amount)
+
+        success(
+          payment_fee_preview: PaymentFeePreview.new(
+            payment_method_id: payment_method.id,
+            currency: order.currency,
+            amount: amount,
+            order_total_after_store_credit: gateway_amount + amount,
+            fee_description: adjustments.one? ? adjustments.first.rule.fee_description : nil,
+            adjustments: adjustments
+          )
+        )
+      end
+
+      private
+
+      def gateway_amount_for(order)
+        [order.order_total_after_store_credit - order.payment_fee_total, 0].max
+      end
+
+      def build_adjustments(order, payment_method, gateway_amount)
+        return [] unless gateway_amount.positive?
+
+        groups = order.line_items.group_by do |line_item|
+          PaymentFeeRule.resolve_for(line_item: line_item, payment_method: payment_method, currency: order.currency)
+        end
+        groups.delete(nil)
+        return [] if groups.empty?
+
+        bases = split(gateway_amount, groups, order)
+        groups.keys.zip(bases).filter_map do |rule, base|
+          amount = round(rule.calculator&.compute(base) || 0, order)
+          PaymentFeePreview::Adjustment.new(rule: rule, amount: amount) if amount.positive?
+        end
+      end
+
+      # Items with no rule still pay their share of the gateway amount, just without a fee, so
+      # weights are taken over every line item, not only the ruled ones.
+      def split(gateway_amount, groups, order)
+        all_items_total = order.line_items.sum(&:total)
+        return [gateway_amount] + Array.new(groups.size - 1, 0) unless all_items_total.positive?
+
+        bases = groups.values.map { |items| round(gateway_amount * items.sum(&:total) / all_items_total, order) }
+        return bases if groups.size < order.line_items.size
+
+        bases[-1] += gateway_amount - bases.sum
+        bases
+      end
+
+      def round(amount, order)
+        amount.to_d.round(::Money::Currency.new(order.currency).exponent)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/payments/find_or_create_decorator.rb

@@ -0,0 +1,18 @@
+module SpreeCmCommissioner
+  module Payments
+    module FindOrCreateDecorator
+      # override: applies the selected method's payment fee before the payment is built, so
+      # `amount: order.order_total_after_store_credit` already includes it. Runs inside
+      # FindOrCreate's transaction, so a failed payment save rolls the fee back with it.
+      def find_or_create_payment(order:, params:, payment_method:)
+        SpreeCmCommissioner::PaymentFees::Apply.call(order: order, payment_method: payment_method)
+
+        super
+      end
+    end
+  end
+end
+
+unless Vpago::Payments::FindOrCreate.included_modules.include?(SpreeCmCommissioner::Payments::FindOrCreateDecorator)
+  Vpago::Payments::FindOrCreate.prepend(SpreeCmCommissioner::Payments::FindOrCreateDecorator)
+end

data/app/services/spree_cm_commissioner/place_resolver.rb

@@ -0,0 +1,95 @@
+module SpreeCmCommissioner
+  # PlaceResolver finds or builds a SpreeCmCommissioner::Place keyed on a stable
+  # upstream identifier instead of the fragile name lookup the polling services
+  # used to do (`Place.find_by(name:)`).
+  #
+  # Lookup order:
+  #   1. IntegrationMapping for (integration, external_id) on Place — authoritative
+  #   2. Legacy backfill: Place.find_by(name:) — adopts pre-mapping rows on first re-sync
+  #   3. Build a new Place
+  #
+  # The resolver persists the Place and its IntegrationMapping. Callers then
+  # wire the Place to a VendorPlace (which has its own mapping).
+  #
+  # `Place#reference` is left to the Google Places geocoder — it's the
+  # canonical Google place_id used by admin tooling and vendor place selection.
+  class PlaceResolver
+    def initialize(integration:, sync_result: nil, geocoder: nil)
+      @integration = integration
+      @sync_result = sync_result || SpreeCmCommissioner::Integrations::Base::SyncResult.new
+      @geocoder = geocoder || SpreeCmCommissioner::GoogleMapsGeocoder.new
+    end
+
+    # @param external_id [String] stable upstream id, e.g. "location-1", "stop-3", "branch-65"
+    # @param name [String] display name
+    # @param code [String, nil] short code
+    # @param lat [Numeric, nil] upstream latitude when available (preferred over geocoding)
+    # @param lon [Numeric, nil] upstream longitude when available
+    # @param geocode_context [String, nil] free-form context for geocoder fallback (e.g. country name)
+    # @return [SpreeCmCommissioner::Place]
+    def resolve(external_id:, name:, code: nil, lat: nil, lon: nil, geocode_context: nil) # rubocop:disable Metrics/ParameterLists
+      mapping = SpreeCmCommissioner::Place.find_or_initialize_integration_mapping(
+        integration_id: @integration.id,
+        external_id: external_id
+      )
+
+      place = resolve_place(mapping, name: name)
+      ensure_coordinates!(place, lat: lat, lon: lon, geocode_context: geocode_context, geocode_query: name)
+
+      @sync_result.track(:place, place) do |tracker|
+        attrs = { name: name }
+        attrs[:code] = code if code.present?
+        place.assign_attributes(attrs)
+        tracker.save_if_changed!(place)
+      end
+
+      finalize_mapping!(mapping, place: place, name: name)
+      place
+    end
+
+    private
+
+    # Pick the Place this mapping should point at: existing internal, legacy adopted, or new.
+    # Adoption-by-name only adopts a Place that does NOT already have an
+    # IntegrationMapping for this integration — otherwise two upstream ids with
+    # the same display name would both adopt the same Place row.
+    def resolve_place(mapping, name:)
+      return mapping.internal if mapping.internal&.persisted?
+
+      legacy = SpreeCmCommissioner::Place.find_by(name: name)
+      if legacy && !already_mapped?(legacy)
+        mapping.internal = legacy
+        legacy
+      else
+        mapping.internal
+      end
+    end
+
+    def already_mapped?(place)
+      SpreeCmCommissioner::IntegrationMapping.exists?(
+        integration_id: @integration.id,
+        internal_type: 'SpreeCmCommissioner::Place',
+        internal_id: place.id
+      )
+    end
+
+    def ensure_coordinates!(place, lat:, lon:, geocode_context:, geocode_query:) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      place.lat ||= lat if lat.present?
+      place.lon ||= lon if lon.present?
+
+      return if place.lat.present? && place.lon.present? && place.reference.present?
+      # Only geocode for brand-new Places. Persisted rows keep whatever coords they already have.
+      return unless place.new_record?
+
+      location_data = @geocoder.fetch_location_data(geocode_query, geocode_context) || {}
+      place.lat = location_data[:lat] if place.lat.blank?
+      place.lon = location_data[:lon] if place.lon.blank?
+      place.reference = location_data[:reference] if place.reference.blank?
+    end
+
+    def finalize_mapping!(mapping, place:, name:)
+      mapping.internal = place if mapping.internal != place
+      mapping.mark_as_active!(external_payload: { name: name })
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/admin_credit.rb

@@ -0,0 +1,44 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Issues a goodwill/support credit to a user's prepaid balance. Distinct from TopUp only
+    # in who initiates it (an admin, not a payment) and the ledger ends up storing `reason`.
+    class AdminCredit
+      prepend ::Spree::ServiceModule::Base
+      extend SpreeCmCommissioner::ServiceModuleThrowable
+      include SpreeCmCommissioner::Prepaid::Mutation
+
+      # rubocop:disable Metrics/ParameterLists
+      def call(user:, amount:, currency:, idempotency_key:, reason:, issuer_tenant_id: nil, admin: nil, private_metadata: {})
+        return failure(nil, 'amount must be positive') unless amount.to_d.positive?
+        return failure(nil, 'unsupported currency') unless Spree::Store.default.supported_currency_codes.include?(currency)
+        return failure(nil, 'reason is required') if reason.blank?
+        return failure(nil, 'admin is required') if admin.nil?
+
+        store_credit = run_serializable do
+          credit = find_or_create_prepaid_credit!(
+            user: user, currency: currency, issuer_tenant_id: issuer_tenant_id,
+            created_by: admin, initial_amount: amount.to_d
+          )
+          check_not_topup_blocked!(credit)
+
+          credit.update!(amount: credit.amount + amount.to_d) unless credit.previously_new_record?
+          write_ledger!(
+            store_credit: credit,
+            transaction_type: 'admin_credit',
+            amount: amount.to_d,
+            idempotency_key: idempotency_key,
+            tenant_id: issuer_tenant_id,
+            admin: admin,
+            private_metadata: private_metadata.merge(reason: reason)
+          )
+          credit
+        end
+
+        success(store_credit)
+      rescue SpreeCmCommissioner::Prepaid::DuplicateTransaction, SpreeCmCommissioner::Prepaid::PrepaidFrozen => e
+        failure(nil, e.message)
+      end
+      # rubocop:enable Metrics/ParameterLists
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/check_top_up_limits.rb

@@ -0,0 +1,47 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Enforces top-up velocity/daily limits (hourly count, daily count, daily amount) --
+    # extracted from TopUp so each limit is independently unit-testable instead of only
+    # reachable through the full money-in transaction.
+    # docs/concepts/store-credit-wallet-system.md Section 8 -- platform-wide for now (the doc's
+    # per-tenant PrepaidConfigResolver was never built). A limit of 0 means "no limit", same
+    # convention the doc uses. Only user-scoped checks; the doc's IP-based "5 distinct users/hour
+    # from one IP" check isn't implemented here -- this has no request context to check it from.
+    class CheckTopUpLimits
+      prepend ::Spree::ServiceModule::Base
+      extend SpreeCmCommissioner::ServiceModuleThrowable
+
+      def call(user:, amount:, currency:)
+        config = SpreeCmCommissioner::Configuration.new
+        completed_topups = SpreeCmCommissioner::PrepaidTransaction.completed.where(user: user, transaction_type: 'top_up')
+
+        # Count-based checks (velocity/fraud signal, not money) deliberately stay currency-agnostic --
+        # 5 top-ups split across USD and KHR is still 5 top-ups.
+        hourly_limit = config.prepaid_max_topups_per_hour.to_i
+        if hourly_limit.positive? && completed_topups.where(created_at: 1.hour.ago..).count >= hourly_limit
+          return failure(nil, "too many top-ups in the last hour (max #{hourly_limit})")
+        end
+
+        todays_topups = completed_topups.where(created_at: Time.current.beginning_of_day..)
+
+        daily_count_limit = config.prepaid_max_topup_count_daily.to_i
+        if daily_count_limit.positive? && todays_topups.count >= daily_count_limit
+          return failure(nil, "daily top-up count limit reached (max #{daily_count_limit})")
+        end
+
+        # Amount-based check must be scoped to this currency and the limit scaled into it (same
+        # rate PrepaidConfig#build_currency_limits shows the client) -- KHR amounts run ~4100x
+        # USD's, so summing across currencies or comparing against the raw USD-denominated
+        # config value would reject (or wrongly allow) almost every non-preferred-currency top-up.
+        rate = config.prepaid_currency_rates[currency].to_f
+        daily_amount_limit = config.prepaid_daily_topup_limit.to_d * rate
+        todays_amount = todays_topups.where(currency: currency).sum(:amount)
+        if daily_amount_limit.positive? && todays_amount + amount > daily_amount_limit
+          return failure(nil, "daily top-up amount limit exceeded (max #{daily_amount_limit})")
+        end
+
+        success(nil)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/freeze.rb

@@ -0,0 +1,58 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Freezes a store credit so PrepaidService money-in operations (and, at 'full' level,
+    # Spree's own spend path via StoreCreditDecorator#spend_blocked?) are blocked.
+    class Freeze
+      prepend ::Spree::ServiceModule::Base
+      extend SpreeCmCommissioner::ServiceModuleThrowable
+      include Mutation
+
+      LEVELS = %w[full topup_only].freeze
+
+      def call(store_credit:, admin:, reason:, level: 'full', until_at: nil)
+        return failure(nil, 'reason is required') if reason.blank?
+        return failure(nil, 'invalid freeze level') unless LEVELS.include?(level)
+
+        # Locked and transactional so a freeze can't interleave with a concurrent money-in
+        # operation (AdminCredit/TopUp lock the same row via Mutation#find_or_create_prepaid_credit!)
+        # -- otherwise a top-up could land in the gap between reading and writing the freeze columns.
+        store_credit = run_serializable do
+          credit = Spree::StoreCredit.lock.find(store_credit.id)
+
+          # A re-freeze (credit was already frozen, e.g. reason/level changed before ever being
+          # lifted) would otherwise overwrite frozen_at/freeze_reason/freeze_level with no trace
+          # of what the prior freeze was -- capture it here, same as Unfreeze does when a freeze
+          # is lifted.
+          write_ledger!(
+            store_credit: credit,
+            transaction_type: 'freeze',
+            amount: 0,
+            idempotency_key: "freeze:#{credit.id}:#{Time.current.to_i / 5}",
+            admin: admin,
+            private_metadata: {
+              reason: reason,
+              level: level,
+              until_at: until_at,
+              prior_frozen_by_id: credit.frozen_by_id,
+              prior_freeze_reason: credit.freeze_reason,
+              prior_freeze_level: credit.freeze_level
+            }
+          )
+
+          credit.update!(
+            frozen_at: Time.current,
+            frozen_by: admin,
+            freeze_reason: reason,
+            freeze_level: level,
+            frozen_until: until_at
+          )
+          credit
+        end
+
+        success(store_credit)
+      rescue SpreeCmCommissioner::Prepaid::DuplicateTransaction => e
+        failure(nil, e.message)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/mutation.rb

@@ -0,0 +1,78 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Raised when a caller-supplied idempotency_key has already been used for a completed
+    # ledger row. Callers (jobs, other services) should rescue this and treat it as a no-op.
+    DuplicateTransaction = Class.new(StandardError)
+
+    # Raised when a money-in operation is attempted against frozen store credit.
+    PrepaidFrozen = Class.new(StandardError)
+
+    # Shared plumbing for the money-in services (TopUp, AdminCredit, ReverseTopUp): opening
+    # a serializable transaction, finding/creating the per-(user, currency, issuer_tenant_id)
+    # prepaid credit under a row lock, and writing the ledger row that mirrors the mutation.
+    # Not a service object itself -- included into the services that are.
+    module Mutation
+      def run_serializable(&block)
+        SpreeCmCommissioner::SerializableTransaction.run(&block)
+      end
+
+      # Spree::StoreCredit requires `amount > 0`, so a brand-new credit is created with
+      # `initial_amount` already applied rather than created at 0 and then topped up --
+      # callers must only add `amount` on top for a credit that already existed.
+      def find_or_create_prepaid_credit!(user:, currency:, issuer_tenant_id:, created_by:, initial_amount:)
+        credit_type = Spree::StoreCreditType.prepaid!
+
+        credit = Spree::StoreCredit.lock.find_by(
+          user_id: user.id,
+          currency: currency,
+          issuer_tenant_id: issuer_tenant_id,
+          type_id: credit_type.id
+        )
+        return credit if credit
+
+        Spree::StoreCredit.create!(
+          user: user,
+          currency: currency,
+          issuer_tenant_id: issuer_tenant_id,
+          credit_type: credit_type,
+          category: Spree::StoreCreditCategory.wallet!,
+          created_by: created_by,
+          amount: initial_amount,
+          store: Spree::Store.default
+        )
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      # admin is a real column (who performed an admin-initiated action), separate from
+      # private_metadata (freeform detail) -- see PrepaidTransaction#admin/store_private_metadata
+      # declarations for why. Named private_metadata, not the ambiguous bare `metadata`, since
+      # PrepaidTransaction also has a separate public_metadata column this never writes to.
+      def write_ledger!(store_credit:, transaction_type:, amount:, idempotency_key:, tenant_id: nil, order: nil, admin: nil, private_metadata: {})
+        SpreeCmCommissioner::PrepaidTransaction.create!(
+          user: store_credit.user,
+          store_credit: store_credit,
+          transaction_type: transaction_type,
+          amount: amount,
+          balance_after: store_credit.amount,
+          currency: store_credit.currency,
+          idempotency_key: idempotency_key,
+          tenant_id: tenant_id,
+          order: order,
+          admin: admin,
+          private_metadata: private_metadata
+        )
+      rescue ActiveRecord::RecordNotUnique
+        raise DuplicateTransaction, "idempotency_key already used: #{idempotency_key}"
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def check_not_topup_blocked!(store_credit)
+        raise PrepaidFrozen, 'store credit is frozen for top-up' if store_credit.topup_blocked?
+      end
+
+      def check_not_spend_blocked!(store_credit)
+        raise PrepaidFrozen, 'store credit is frozen for spend' if store_credit.spend_blocked?
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/reverse_order_top_up.rb

@@ -0,0 +1,23 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Reverses a top-up order's credit in one call -- looks up the order's top_up ledger row
+    # itself and delegates to ReverseTopUp, so callers (PrepaidReverseTopUpJob, etc.) only need
+    # to pass the order instead of first finding the transaction and its store_credit themselves.
+    class ReverseOrderTopUp
+      prepend ::Spree::ServiceModule::Base
+
+      def call(order:, reason: nil, private_metadata: {})
+        txn = SpreeCmCommissioner::PrepaidTransaction.find_by(order: order, transaction_type: 'top_up')
+        return failure(nil, 'no top-up transaction found for order') if txn.nil?
+
+        SpreeCmCommissioner::Prepaid::ReverseTopUp.call(
+          store_credit: txn.store_credit,
+          amount: order.total,
+          idempotency_key: "cancel:order:#{order.number}",
+          reason: reason,
+          private_metadata: private_metadata
+        )
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/reverse_top_up.rb

@@ -0,0 +1,53 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Claws back a prepaid credit, capped at the unspent amount -- amount_used can never be
+    # reduced, so a partially-spent top-up can only be reversed for what remains available.
+    # The ledger records the amount actually reversed (which may be less than requested) so
+    # reconciliation reconstructs the balance exactly.
+    class ReverseTopUp
+      prepend ::Spree::ServiceModule::Base
+      extend SpreeCmCommissioner::ServiceModuleThrowable
+      include SpreeCmCommissioner::Prepaid::Mutation
+
+      NothingToReverse = Class.new(StandardError)
+
+      # rubocop:disable Metrics/ParameterLists,Lint/MissingCopEnableDirective
+      # admin is optional, not required (unlike AdminCredit) -- this service has a second,
+      # system-initiated caller (ReverseOrderTopUp, via PrepaidReverseTopUpJob, reversing a
+      # top-up order's credit on cancellation) with no admin in context at all.
+      def call(store_credit:, amount:, idempotency_key:, admin: nil, reason: nil, private_metadata: {})
+        return failure(nil, 'amount must be positive') unless amount.to_d.positive?
+
+        store_credit = run_serializable do
+          # Deliberately no check_not_topup_blocked!/check_not_spend_blocked! here: freezing a
+          # wallet blocks the *account holder* from topping up or spending -- it must never block
+          # this administrative/system clawback, or freezing a wallet during a fraud review would
+          # actually protect the fraudulent credit from being reversed.
+          credit = Spree::StoreCredit.lock.find(store_credit.id)
+
+          available = credit.amount - credit.amount_used - credit.amount_authorized
+          reversed = [amount.to_d, available].min
+          raise NothingToReverse if reversed <= 0
+
+          credit.update!(amount: credit.amount - reversed)
+          write_ledger!(
+            store_credit: credit,
+            transaction_type: 'reverse_top_up',
+            amount: -reversed,
+            idempotency_key: idempotency_key,
+            tenant_id: credit.issuer_tenant_id,
+            admin: admin,
+            private_metadata: private_metadata.merge(reason: reason, requested_amount: amount.to_d, reversed_amount: reversed)
+          )
+          credit
+        end
+
+        success(store_credit)
+      rescue SpreeCmCommissioner::Prepaid::DuplicateTransaction => e
+        failure(nil, e.message)
+      rescue NothingToReverse
+        failure(nil, 'nothing available to reverse')
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/top_up.rb

@@ -0,0 +1,68 @@
+module SpreeCmCommissioner
+  module Prepaid
+    # Credits a user's prepaid store credit balance (real-money top-up). One writer path
+    # shared with AdminCredit/ReverseTopUp via Prepaid::Mutation -- see
+    # docs/concepts/store-credit-wallet-system.md Section 4.
+    class TopUp
+      prepend ::Spree::ServiceModule::Base
+      extend SpreeCmCommissioner::ServiceModuleThrowable
+      include SpreeCmCommissioner::Prepaid::Mutation
+
+      LimitExceeded = Class.new(StandardError)
+
+      # rubocop:disable Metrics/ParameterLists
+      def call(user:, amount:, currency:, idempotency_key:, issuer_tenant_id: nil, order: nil, private_metadata: {})
+        return failure(nil, 'amount must be positive') unless amount.to_d.positive?
+        return failure(nil, 'unsupported currency') unless Spree::Store.default.supported_currency_codes.include?(currency)
+
+        store_credit = run_serializable do
+          SpreeCmCommissioner::Prepaid::CheckTopUpLimits.call!(user: user, amount: amount.to_d, currency: currency)
+
+          # The paying customer authorized this via their own payment -- no admin/system
+          # account involved, so they're the natural `created_by` (Spree only requires it be
+          # *a* Spree::User; nothing gates it to an admin role).
+          credit = find_or_create_prepaid_credit!(
+            user: user, currency: currency, issuer_tenant_id: issuer_tenant_id,
+            created_by: user, initial_amount: amount.to_d
+          )
+          check_not_topup_blocked!(credit)
+          check_max_balance!(credit, amount.to_d)
+
+          credit.update!(amount: credit.amount + amount.to_d) unless credit.previously_new_record?
+          write_ledger!(
+            store_credit: credit,
+            transaction_type: 'top_up',
+            amount: amount.to_d,
+            idempotency_key: idempotency_key,
+            tenant_id: issuer_tenant_id,
+            order: order,
+            private_metadata: private_metadata
+          )
+          credit
+        end
+
+        success(store_credit)
+      rescue SpreeCmCommissioner::Prepaid::DuplicateTransaction, SpreeCmCommissioner::Prepaid::PrepaidFrozen,
+             SpreeCmCommissioner::ServiceFailure, LimitExceeded => e
+        failure(nil, e.message)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      # max_balance is denominated in Spree::Store.default#default_currency -- scale it into
+      # credit.currency's own magnitude (same PrepaidConfig#build_currency_limits formula) before
+      # comparing, or a KHR wallet's ~4100x-larger raw numbers would trip the USD-sized cap
+      # almost immediately.
+      def check_max_balance!(credit, amount)
+        config = SpreeCmCommissioner::Configuration.new
+        rate = config.prepaid_currency_rates[credit.currency].to_f
+        max_balance = config.prepaid_max_balance.to_d * rate
+        return unless max_balance.positive?
+        return unless credit.amount + amount > max_balance
+
+        raise LimitExceeded, "store credit balance cap exceeded (max #{max_balance})"
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/prepaid/unfreeze.rb

@@ -0,0 +1,47 @@
+module SpreeCmCommissioner
+  module Prepaid
+    class Unfreeze
+      prepend ::Spree::ServiceModule::Base
+      extend SpreeCmCommissioner::ServiceModuleThrowable
+      include Mutation
+
+      def call(store_credit:, admin: nil)
+        # Same locking rationale as Freeze#call -- avoid interleaving with a concurrent money-in
+        # operation that locks the same row.
+        store_credit = run_serializable do
+          credit = Spree::StoreCredit.lock.find(store_credit.id)
+
+          # Freeze columns are about to be cleared -- capture them here so who lifted the freeze,
+          # and what was being lifted, isn't lost. Idempotency key is keyed to this specific
+          # freeze (frozen_at), so a double-submitted unfreeze can't write two ledger rows, while
+          # a later freeze/unfreeze cycle on the same credit still gets its own row.
+          if credit.frozen_at.present?
+            write_ledger!(
+              store_credit: credit,
+              transaction_type: 'unfreeze',
+              amount: 0,
+              idempotency_key: "unfreeze:#{credit.id}:#{credit.frozen_at.to_i}",
+              admin: admin,
+              private_metadata: {
+                prior_frozen_by_id: credit.frozen_by_id,
+                prior_freeze_reason: credit.freeze_reason,
+                prior_freeze_level: credit.freeze_level
+              }
+            )
+          end
+
+          credit.update!(
+            frozen_at: nil,
+            frozen_by: nil,
+            freeze_reason: nil,
+            freeze_level: nil,
+            frozen_until: nil
+          )
+          credit
+        end
+
+        success(store_credit)
+      end
+    end
+  end
+end