spree_cm_commissioner 2.13.4 → 2.13.7

data/app/helpers/spree/admin/reschedule_requests_helper.rb

@@ -0,0 +1,79 @@
+module Spree
+  module Admin
+    module RescheduleRequestsHelper
+      STATE_BADGE_CLASSES = {
+        'pending_approval' => 'badge-warning',
+        'pending_payment' => 'badge-info',
+        'processing' => 'badge-primary',
+        'completed' => 'badge-success',
+        'rejected' => 'badge-danger',
+        'processing_failed' => 'badge-danger',
+        'cancelled' => 'badge-secondary',
+        'expired' => 'badge-dark'
+      }.freeze
+
+      # Drives Spree's always-visible quick-search box. Covers both identities:
+      # the account that booked (`user`, which the detail page labels Customer)
+      # and the contact details captured on the order, which are often
+      # different people and, for guest checkout, the only ones present.
+      SEARCH_PREDICATE = "#{%i[
+        number
+        order_number
+        order_email
+        order_phone_number
+        order_intel_phone_number
+        user_email
+        user_phone_number
+      ].join('_or_')}_cont".freeze
+
+      def reschedule_request_search_predicate
+        SEARCH_PREDICATE
+      end
+
+      def reschedule_request_state_badge(state)
+        klass = STATE_BADGE_CLASSES.fetch(state.to_s, 'badge-light')
+        content_tag :span, state.to_s.humanize, class: "badge #{klass}"
+      end
+
+      # `approved` is a pseudo-status: `with_status` resolves it through
+      # `approved_at`, not `state`.
+      def reschedule_request_status_options
+        states = SpreeCmCommissioner::RescheduleRequest.state_machines[:state].states.map { |s| s.name.to_s }
+        (states + ['approved']).map { |status| [status.humanize, status] }
+      end
+
+      def reschedule_request_fee_label(request)
+        return "#{request.fee_percentage.to_d.round(2)}%" if request.fee_percentage.to_d.positive?
+
+        request.display_fee_amount
+      end
+
+      def reschedule_snapshot_guests(snapshot)
+        return [] if snapshot.blank?
+
+        ids = SpreeCmCommissioner::RescheduleRequests::GuestSelection.snapshot_guest_ids(snapshot)
+        return [] if ids.blank?
+
+        SpreeCmCommissioner::Guest.where(id: ids).order(:id)
+      end
+
+      def reschedule_guest_label(guest)
+        guest.display_name_with_bib.presence || "Guest ##{guest.id}"
+      end
+
+      def reschedule_compensation_link(request)
+        record = request.reschedule_compensation
+        return content_tag(:span, Spree.t(:none), class: 'text-muted') if record.blank?
+
+        case record
+        when Spree::Promotion
+          link_to record.name.presence || record.id, spree.edit_admin_promotion_path(record)
+        when Spree::StoreCredit
+          record.user_id ? link_to(record.display_amount, spree.admin_user_store_credit_path(record.user_id, record)) : record.display_amount
+        else
+          "#{record.class.name.demodulize.titleize} #{record.id}"
+        end
+      end
+    end
+  end
+end

data/app/helpers/spree_cm_commissioner/admin/fee_rules_helper.rb

@@ -0,0 +1,23 @@
+module SpreeCmCommissioner
+  module Admin
+    # Shared by the service fee and payment fee rule lists: the Scope column links to what the
+    # rule is scoped to (the rule itself is opened with the row's edit action).
+    module FeeRulesHelper
+      def fee_rule_scope_link(rule)
+        path = fee_rule_scope_path(rule)
+        path ? link_to(rule.scope_label, path) : rule.scope_label
+      end
+
+      private
+
+      def fee_rule_scope_path(rule)
+        case rule.ruleable
+        when Spree::Product then spree.edit_admin_product_path(rule.ruleable)
+        when Spree::Taxon then spree.edit_admin_taxonomy_taxon_path(rule.ruleable.taxonomy_id, rule.ruleable.id)
+        when Spree::Vendor then spree.edit_admin_vendor_path(rule.ruleable)
+        when nil then rule.tenant ? spree.edit_admin_tenant_path(rule.tenant) : nil
+        end
+      end
+    end
+  end
+end

data/app/interactors/spree_cm_commissioner/create_ticket.rb

@@ -136,6 +136,7 @@ module SpreeCmCommissioner
         option_type_ids: context.params[:option_type_ids],
         allow_anonymous_booking: context.params[:allow_anonymous_booking],
         allow_self_check_in: context.params[:allow_self_check_in],
+        offline: context.params[:offline] || false,
         purchasable_on: context.params[:purchasable_on] || 'both'
       }
     end

data/app/jobs/spree_cm_commissioner/audit_event_job.rb

@@ -0,0 +1,29 @@
+module SpreeCmCommissioner
+  class AuditEventJob < ApplicationUniqueJob
+    def perform(options = {})
+      SpreeCmCommissioner::AuditEvent.create!(
+        event_type: options[:event_type],
+        success: options.fetch(:success, true),
+        auditable: options[:auditable],
+        user: options[:user],
+        correlation_id: options[:correlation_id],
+        attempt: options.fetch(:attempt, 0),
+        metadata: options.fetch(:metadata, {}),
+        retention_until: options[:retention_until]
+      )
+    rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved => e
+      # Log validation errors but don't retry - these are data issues, not transient failures
+      CmAppLogger.log(
+        label: 'AuditEventJob validation failed - non-retryable',
+        data: {
+          event_type: options[:event_type],
+          error_class: e.class.name,
+          error_message: e.message,
+          validation_errors: e.record&.errors&.full_messages
+        }
+      )
+      # Return nil to indicate the job completed (but audit wasn't saved)
+      nil
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/prepaid_reconciliation_cron_job.rb

@@ -0,0 +1,9 @@
+module SpreeCmCommissioner
+  class PrepaidReconciliationCronJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      SpreeCmCommissioner::PrepaidReconciliationService.run_daily
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/prepaid_reverse_top_up_job.rb

@@ -0,0 +1,16 @@
+module SpreeCmCommissioner
+  # Claws back a top-up's credit when its funding order is canceled -- nothing else in the
+  # codebase does this today, so without this job a canceled top-up order silently leaves the
+  # customer holding wallet balance nothing actually paid for.
+  # ApplicationUniqueJob (deduped by order_id): same reasoning as PrepaidTopUpCreditJob -- the
+  # ledger's idempotency_key already makes a duplicate run a safe no-op, this just skips wasting
+  # a SERIALIZABLE transaction attempt on it.
+  class PrepaidReverseTopUpJob < ApplicationUniqueJob
+    def perform(order_id:)
+      order = Spree::Order.find_by(id: order_id)
+      return if order.nil? || !order.canceled? || !order.prepaid_top_up_order?
+
+      SpreeCmCommissioner::Prepaid::ReverseOrderTopUp.call(order: order, reason: 'order canceled')
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/prepaid_setup_types_job.rb

@@ -0,0 +1,24 @@
+module SpreeCmCommissioner
+  # One-time setup for the prepaid wallet's store-credit category, plus every
+  # Spree::StoreCreditType in STORE_CREDIT_TYPES (our own types and core's generic
+  # "Expiring"/"Non-expiring" -- harmless to seed those here too, find_or_create_by! is a no-op
+  # if core's own associate_credit_type already created them). Enqueue once per environment
+  # before enabling the feature (SpreeCmCommissioner::PrepaidSetupTypesJob.perform_later) --
+  # idempotent, so re-running it (retry, or by accident) is a no-op.
+  # ApplicationUniqueJob (not ApplicationJob) since it takes no arguments -- two concurrent runs
+  # could otherwise both miss on find_or_create_by!'s SELECT and race on the CREATE.
+  class PrepaidSetupTypesJob < ApplicationUniqueJob
+    def perform
+      category = Spree::StoreCreditCategory.wallet!
+
+      StoreCreditTypeDecorator::STORE_CREDIT_TYPES.each do |type_name|
+        Spree::StoreCreditType.find_or_create_by!(name: type_name)
+      end
+
+      CmAppLogger.log(
+        label: 'PrepaidSetupTypesJob completed',
+        data: { category: category.name, types: StoreCreditTypeDecorator::STORE_CREDIT_TYPES }
+      )
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/prepaid_top_up_credit_job.rb

@@ -0,0 +1,31 @@
+module SpreeCmCommissioner
+  # Credits the wallet for a prepaid_top_up order once the order completes.
+  # Deliberately does not wait for payment_fulfilled? -- pre-authorized payment methods
+  # (e.g. PayWay v2 with pre-auth) already hold the customer's funds at authorization
+  # time, and capture is done manually later -- see docs/concepts/store-credit-wallet-system.md
+  # Section 4.3.
+  # ApplicationUniqueJob (deduped by order_id): the ledger's idempotency_key already makes a
+  # duplicate run a safe no-op, this just skips wasting a SERIALIZABLE transaction attempt on it.
+  class PrepaidTopUpCreditJob < ApplicationUniqueJob
+    def perform(order_id:)
+      order = Spree::Order.find_by(id: order_id)
+      return if order.nil? || !order.complete? || !order.prepaid_top_up_order?
+
+      result = SpreeCmCommissioner::Prepaid::TopUp.call(
+        user: order.user,
+        amount: order.total,
+        currency: order.currency,
+        idempotency_key: "topup:order:#{order.number}",
+        issuer_tenant_id: order.tenant_id,
+        order: order
+      )
+
+      return if result.success?
+
+      CmAppLogger.error(
+        label: 'PrepaidTopUpCreditJob#perform not credited',
+        data: { order: order.number, error: result.error.to_s }
+      )
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/reschedule_requests/approval_reminder_job.rb

@@ -0,0 +1,17 @@
+# Per-request vendor decision nudge. Recipient: the VENDOR, over Telegram.
+#
+# Enqueued from the model's `after_commit :schedule_approval_reminder` with
+# `wait_until:` set a fraction into the decision window. Thin wrapper - the state
+# re-check and the idempotency stamp live in `SendApprovalReminder`.
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class ApprovalReminderJob < ApplicationJob
+      def perform(options = {})
+        request = SpreeCmCommissioner::RescheduleRequest.find_by(id: options[:reschedule_request_id])
+        return if request.nil?
+
+        SpreeCmCommissioner::RescheduleRequests::Notifications::SendApprovalReminder.call(reschedule_request: request)
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/reschedule_requests/execute_job.rb

@@ -0,0 +1,20 @@
+# Runs Execute once the balance-due payment is captured. Enqueued from the
+# payment-completed hook so execution happens AFTER the payment commits — a
+# failed Execute then lands in processing_failed without rolling back the money.
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class ExecuteJob < ApplicationJob
+      def perform(options = {})
+        request = SpreeCmCommissioner::RescheduleRequest.find_by(id: options[:reschedule_request_id])
+        return if request.nil?
+        return unless request.pending_payment? # idempotent: only the awaiting-payment request executes
+
+        # Authoritative paid check: the enqueuing hook fires mid-transaction,
+        # before payment_state settles. Nothing moves unpaid.
+        return unless request.order.payment_fulfilled?
+
+        SpreeCmCommissioner::RescheduleRequests::Execute.call(reschedule_request: request)
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/reschedule_requests/expire_overdue_requests_job.rb

@@ -0,0 +1,12 @@
+# Cron safety net (every 15 minutes). Catches RescheduleRequests the
+# per-request `ExpireRequestJob` missed (worker restart, queue loss).
+# Thin wrapper — all iteration logic lives in `RescheduleRequests::ExpireOverdueRequests`.
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class ExpireOverdueRequestsJob < ApplicationJob
+      def perform
+        SpreeCmCommissioner::RescheduleRequests::ExpireOverdueRequests.call
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/reschedule_requests/expire_request_job.rb

@@ -0,0 +1,15 @@
+# Per-request expiry. Enqueued from the model's `after_commit
+# :schedule_expiration` with `wait_until: expires_at`. Thin wrapper that
+# finds the request and hands off to `RescheduleRequests::ExpireRequest`.
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class ExpireRequestJob < ApplicationJob
+      def perform(options = {})
+        request = SpreeCmCommissioner::RescheduleRequest.find_by(id: options[:reschedule_request_id])
+        return if request.nil?
+
+        SpreeCmCommissioner::RescheduleRequests::ExpireRequest.call(reschedule_request: request)
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/reschedule_requests/payment_reminder_job.rb

@@ -0,0 +1,17 @@
+# Per-request payment nudge. Recipient: the CUSTOMER, over FCM plus the in-app list.
+#
+# Enqueued from the model's `after_commit :schedule_payment_reminder` with
+# `wait_until:` set a fraction into the payment window. Thin wrapper - the state
+# re-check and the idempotency stamp live in `SendPaymentReminder`.
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class PaymentReminderJob < ApplicationJob
+      def perform(options = {})
+        request = SpreeCmCommissioner::RescheduleRequest.find_by(id: options[:reschedule_request_id])
+        return if request.nil?
+
+        SpreeCmCommissioner::RescheduleRequests::Notifications::SendPaymentReminder.call(reschedule_request: request)
+      end
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/audit_wrapper.rb

@@ -0,0 +1,139 @@
+module SpreeCmCommissioner
+  # AuditWrapper is a reusable mixin for classes that make external API calls.
+  #
+  # It wraps an API call in a three-event lifecycle:
+  #   1. <event_base>.request  – logged before the call
+  #   2. <event_base>.response – logged after a successful call (includes timing)
+  #   3. <event_base>.failed   – logged when the block raises, then re-raises
+  #
+  # Metadata follows this canonical shape:
+  #   {
+  #     request:  { method:, endpoint:, body:, params: },
+  #     response: { status:, body: },
+  #     timing:   { duration_ms: },
+  #     error:    nil | { message: }
+  #   }
+  #
+  # Usage:
+  #   include SpreeCmCommissioner::AuditWrapper
+  #
+  #   with_audit(
+  #     event_base: 'bookmebus.order.hold',
+  #     request:    { method: 'POST', endpoint: '/api/v2/trip_reservations', body: body },
+  #     auditable:  order,
+  #     user:       current_user
+  #   ) do
+  #     post("#{BASE_PATH}/trip_reservations", body)
+  #   end
+
+  module AuditWrapper
+    extend ActiveSupport::Concern
+
+    def with_audit(event_base:, request: {}, auditable: nil, user: nil, # rubocop:disable Metrics/ParameterLists
+                   attempt: 0, retention_days: nil
+    )
+      correlation_id = SecureRandom.uuid
+
+      shared = {
+        auditable: auditable,
+        user: user,
+        correlation_id: correlation_id,
+        attempt: attempt,
+        retention_days: retention_days
+      }
+
+      # 1. Log the outbound request
+      AuditLogger.log!(
+        **shared,
+        event_type: "#{event_base}.request",
+        success: true,
+        metadata: build_request_metadata(request)
+      )
+
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result     = yield
+      duration   = elapsed_ms(started_at)
+
+      # 2. Log the successful response
+      AuditLogger.log!(
+        **shared,
+        event_type: "#{event_base}.response",
+        success: true,
+        metadata: build_response_metadata(request, result, duration)
+      )
+
+      result
+    rescue StandardError => e
+      duration = elapsed_ms(started_at || Process.clock_gettime(Process::CLOCK_MONOTONIC))
+
+      # 3. Log the failure event
+      AuditLogger.log!(
+        **shared,
+        event_type: "#{event_base}.failed",
+        success: false,
+        metadata: build_error_metadata(request, e, duration)
+      )
+
+      raise
+    end
+
+    private
+
+    def build_request_metadata(request)
+      {
+        request: normalize_request(request),
+        response: nil,
+        timing: nil,
+        error: nil
+      }
+    end
+
+    def build_response_metadata(request, result, duration_ms)
+      status, body = extract_response(result)
+
+      {
+        request: normalize_request(request),
+        response: { status: status, body: body },
+        timing: { duration_ms: duration_ms },
+        error: nil
+      }
+    end
+
+    def build_error_metadata(request, error, duration_ms)
+      {
+        request: normalize_request(request),
+        response: nil,
+        timing: { duration_ms: duration_ms },
+        error: { message: error.message }
+      }
+    end
+
+    def normalize_request(request)
+      {
+        method: request[:method],
+        endpoint: request[:endpoint],
+        body: request[:body],
+        params: request[:params]
+      }
+    end
+
+    # Try to extract status + body from common response objects.
+    # Falls back to inspecting the raw result.
+    def extract_response(result)
+      if result.respond_to?(:status) && result.respond_to?(:body)
+        [result.status, result.body]
+      elsif result.is_a?(Array)
+        # Handle arrays of resource objects
+        [nil, result.map(&:to_h)]
+      elsif result.respond_to?(:to_h)
+        [nil, result.to_h]
+      else
+        [nil, result.inspect]
+      end
+    end
+
+    def elapsed_ms(started_at)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/integrations/inventory_sync_cachable.rb

@@ -0,0 +1,9 @@
+module SpreeCmCommissioner
+  module Integrations
+    module InventorySyncCachable
+      def sync_cache_ttl
+        ENV.fetch('SYNC_CACHE_TTL', '300').to_i.seconds
+      end
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/option_type_attr_type.rb

@@ -45,7 +45,8 @@ module SpreeCmCommissioner
       'ticket-type' => 'string',
       'seat-type' => 'string',
       'intercity-taxi' => 'string',
-      'vote-package' => 'integer'
+      'vote-package' => 'integer',
+      'top-up-amount' => 'integer'
     }.freeze
 
     included do

data/app/models/concerns/spree_cm_commissioner/order_prepaid_payment.rb

@@ -0,0 +1,15 @@
+module SpreeCmCommissioner
+  module OrderPrepaidPayment
+    extend ActiveSupport::Concern
+
+    # Applies the buyer's eligible prepaid/coin balance (FEFO + issuer-scoped, Section 5.2 of
+    # docs/concepts/store-credit-wallet-system.md) to this order's outstanding balance. Goes
+    # through the injectable Spree::Dependencies point rather than referencing
+    # SpreeCmCommissioner::Checkout::AddStoreCreditPayments directly, so callers stay agnostic
+    # of the concrete service class.
+    def apply_prepaid_payment!(amount: nil)
+      result = Spree::Dependencies.checkout_add_store_credit_service.constantize.call(order: self, amount: amount)
+      result.success?
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/order_state_machine.rb

@@ -18,6 +18,10 @@ module SpreeCmCommissioner
       # line item changes between steps.
       state_machine.before_transition to: :payment, do: :create_service_fee_charge!
       state_machine.before_transition from: :address, do: :create_service_fee_charge!
+      state_machine.before_transition to: :payment, do: :clear_stale_payment_fee!
+      state_machine.before_transition from: :address, do: :clear_stale_payment_fee!
+
+      state_machine.after_transition to: :payment, do: :apply_prepaid_payment_on_checkout, if: :user, unless: :skip_auto_apply_prepaid_payment?
 
       # Fails fast, before any of the other before_transition/around_transition work below runs
       # (external-system unstock, Redis unstock, notifications, ...), when the inventory hold has
@@ -29,6 +33,7 @@ module SpreeCmCommissioner
       # purely an optimization so a doomed completion attempt doesn't first burn a call to the
       # external system and a Redis round trip.
       state_machine.before_transition to: :complete, do: :validate_inventory_hold_before_complete
+
       state_machine.before_transition to: :complete, do: :request, if: :need_confirmation?
       state_machine.before_transition to: :complete, do: :finalize_guests_and_bibs
       state_machine.before_transition to: :complete, do: :generate_completion_steps!, if: :product_completion_steps_exist?
@@ -51,9 +56,11 @@ module SpreeCmCommissioner
       state_machine.after_transition to: :canceled, do: :precalculate_conversion
       state_machine.after_transition to: :canceled, do: :restock_inventory!
       state_machine.after_transition to: :canceled, do: :de_allocate_resources
+      state_machine.after_transition to: :canceled, do: :enqueue_prepaid_top_up_reversal_job
 
       state_machine.after_transition to: :complete, do: :increment_route_fulfilled_order_count
       state_machine.after_transition to: :complete, do: :allocate_resources
+      state_machine.after_transition to: :complete, do: :enqueue_prepaid_top_up_credit_job
       state_machine.after_transition to: :complete, do: :run_order_complete_alerts
 
       scope :accepted, -> { where(request_state: 'accepted') }
@@ -100,6 +107,26 @@ module SpreeCmCommissioner
       end
     end
 
+    # Best-effort, like apply_prepaid_payment!'s other callers: a user with no (or no
+    # currency-matching) store credit just doesn't get a payment here, and the app can still
+    # remove/reapply it afterwards through the existing checkout store-credit endpoints.
+    def apply_prepaid_payment_on_checkout
+      apply_prepaid_payment!
+    end
+
+    # subscription?: SubscriptionsOrderCreator already builds its own store-credit payment via
+    # create_default_payment_if_eligble, then drives the order through Spree::Checkout::Advance,
+    # which passes through :payment. Running this callback too would invalidate that payment
+    # mid-flow and rebuild a second one, racing the balance/capture logic already in progress.
+    #
+    # prepaid_top_up_order?: buying wallet balance with wallet balance is circular --
+    # Checkout::AddStoreCreditPayments already refuses these (see topup_paid_with_store_credit?),
+    # so this is belt-and-suspenders to keep the callback a visible no-op instead of a call that
+    # always fails deep in the service.
+    def skip_auto_apply_prepaid_payment?
+      subscription? || prepaid_top_up_order?
+    end
+
     # override
     def deliver_order_confirmation_email
       return if requested?
@@ -156,18 +183,21 @@ module SpreeCmCommissioner
         yield if block_given? # Equal to block.call
 
         # After the transition is complete, the following code will execute first before proceeding to other `after_transition` callbacks.
-        # This ensures that if `reserve_order_holds!` or `unstock_inventory_in_redis!` fails, the state will be rolled back,
+        # This ensures that if `reserve_order_holds!`, `unstock_inventory_in_redis!`, or
+        # `capture_authorized_store_credit_payments!` fails, the state will be rolled back,
         # and neither the `finalize!` method nor any notifications will be triggered.
-        # The payment will be reversed in vPago gem, and `Spree::Checkout::Complete` will be called, which checks `order.reload.complete?`.
-        # This is critical because if the order state is complete, the payment will be marked as paid.
-
+        # `unstock_inventory_from_external_system!` is the one exception: it calls out to a real
+        # external system, so a DB rollback here can't undo it, and any gateway-backed remainder
+        # payment already captured earlier (in process_payments!, before this transaction) can't be
+        # undone by this rollback either -- those still need vPago's own reversal/manual refund.
+        # Store credit is different: capture_authorized_store_credit_payments! is a plain DB write
+        # against our own tables, so it rolls back cleanly with everything else here -- no manual
+        # refund needed for that leg specifically.
+
+        capture_authorized_store_credit_payments!
         unstock_inventory_from_external_system!
         reserve_order_holds!
         unstock_inventory_in_redis!
-
-        # We rollback only order state, and we keep payment state as it is.
-        # We implement payment in vPago gem, and it will be reversed in the gem.
-        # Some bank has api for refund, but some don't have the api to refund yet. So we keep the payment state as it is and refund manually.
       end
     rescue StandardError => e
       CmAppLogger.log(
@@ -178,6 +208,16 @@ module SpreeCmCommissioner
       raise e
     end
 
+    # Store credit is authorized (not captured) at process_payments! time -- see
+    # Spree::PaymentMethod::StoreCredit#auto_capture, set false for this exact reason. Capturing
+    # runs first here, before stock is confirmed, but that's still safe: this whole method body is
+    # one transaction (see unstock_inventory! above), so if reserve_order_holds! or any later step
+    # fails, this capture rolls back along with it -- the customer is never left having spent
+    # store credit on an order that didn't actually complete.
+    def capture_authorized_store_credit_payments!
+      payments.valid.store_credits.where(state: :pending).find_each(&:capture!)
+    end
+
     def restock_inventory!
       ActiveRecord::Base.transaction do
         restock_inventory_from_external_system!
@@ -389,6 +429,16 @@ module SpreeCmCommissioner
       SpreeCmCommissioner::VotingCreditAllocationJob.perform_later(order_id: id)
     end
 
+    def enqueue_prepaid_top_up_credit_job
+      SpreeCmCommissioner::PrepaidTopUpCreditJob.perform_later(order_id: id)
+    end
+
+    # Same shape as enqueue_prepaid_top_up_credit_job above: always enqueue, the job itself
+    # re-checks prepaid_top_up_order? and no-ops for every other order.
+    def enqueue_prepaid_top_up_reversal_job
+      SpreeCmCommissioner::PrepaidReverseTopUpJob.perform_later(order_id: id)
+    end
+
     def de_allocate_resources
       SpreeCmCommissioner::VotingCreditDeAllocationJob.perform_later(order_id: id)
     end

data/app/models/concerns/spree_cm_commissioner/percent_fee_calculable.rb

@@ -0,0 +1,36 @@
+module SpreeCmCommissioner
+  # "10% + $0.25" fee shape shared by ServiceFeePercent and PaymentFeePercent. Lives outside
+  # SpreeCmCommissioner::Calculators on purpose: PricingAction.available_calculator_types lists
+  # every constant in that namespace, and a module there would show up as a pickable calculator
+  # type. The flat part is named like the *FlatAmount calculators' preference so admins see one
+  # term; each including calculator decides what it's multiplied by (per unit for service fees,
+  # once per payment for payment fees).
+  module PercentFeeCalculable
+    extend ActiveSupport::Concern
+
+    included do
+      preference :percent, :decimal, default: 0
+      preference :flat_amount, :decimal, default: 0
+    end
+
+    def fee_description(currency:)
+      percent = "#{preferred_percent.to_d.round(2).to_s('F')}%"
+      return percent unless preferred_flat_amount.to_d.positive?
+
+      flat = Spree::Money.new(preferred_flat_amount, currency: currency).to_s
+      return flat if preferred_percent.to_d.zero?
+
+      Spree.t(:fee_percent_plus_flat, percent: percent, flat: flat)
+    end
+
+    private
+
+    # Nothing to charge on a zero base (a free line item, or store credit covering the order),
+    # so the flat part isn't added on its own there either.
+    def percent_plus_flat(base, flat)
+      return 0 unless base.to_d.positive?
+
+      (base * preferred_percent / 100) + flat
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/product_type.rb

@@ -5,9 +5,13 @@ module SpreeCmCommissioner
   module ProductType
     extend ActiveSupport::Concern
 
-    PRODUCT_TYPES = %i[accommodation service ecommerce transit show_episode vote_package advertisement].freeze
+    PRODUCT_TYPES = %i[accommodation service ecommerce transit show_episode vote_package advertisement prepaid_top_up].freeze
     PERMANENT_STOCK_PRODUCT_TYPES = %w[accommodation service transit].freeze
-    PRE_INVENTORY_DAYS = { 'transit' => 90, 'accommodation' => 365, 'service' => 30 }.freeze
+    PRE_INVENTORY_DAYS = {
+      'transit' => ENV.fetch('PRE_INVENTORY_DAYS_TRANSIT', 180).to_i,
+      'accommodation' => ENV.fetch('PRE_INVENTORY_DAYS_ACCOMMODATION', 365).to_i,
+      'service' => ENV.fetch('PRE_INVENTORY_DAYS_SERVICE', 180).to_i
+    }.freeze
 
     included do
       enum product_type: PRODUCT_TYPES if table_exists? && column_names.include?('product_type')