spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/payment_method.rb

@@ -3,26 +3,58 @@ module Spree
     has_prefix_id :pm  # Stripe: pm_
 
     acts_as_paranoid
-    acts_as_list
+    # Scoped like every other store-owned list (Collection, Market,
+    # PriceList): without it, position assignment and reordering shift rows
+    # across ALL stores.
+    acts_as_list scope: :store_id
 
     include Spree::SingleStoreResource
-    include Spree::Metafields
+    include Spree::HasListPosition
+    include Spree::StorePreferences
+    include Spree::HasCustomFields
     include Spree::Metadata
-    include Spree::DisplayOn
+    include Spree::CaptureMethod
     if defined?(Spree::Security::PaymentMethods)
       include Spree::Security::PaymentMethods
     end
-    # Multi-store sharing moved to the spree_multi_store extension in 5.6.
-    include Spree::LegacyMultiStoreSupport unless defined?(SpreeMultiStore)
+
+    # Blank falls back to the store, so a method only overrides when a merchant
+    # deliberately picks one — the meaning the auto_capture boolean already had.
+    normalizes :capture_method, with: ->(value) { value.presence }
+
+    validates :capture_method, inclusion: { in: Spree::CaptureMethod::CAPTURE_METHODS }, allow_nil: true
+
+    # Provider subclasses override the payment-session methods wholesale, so
+    # tracing instrumentation must be prepended to each subclass — prepended
+    # to this base class it would sit below the override and never run.
+    #
+    # @param subclass [Class] the inheriting payment method class
+    # @return [void]
+    def self.inherited(subclass)
+      super
+      subclass.prepend(Spree::PaymentMethod::SessionInstrumentation)
+    end
 
     scope :active,    -> { where(active: true).order(position: :asc) }
-    scope :available, -> { active.where(display_on: [:front_end, :back_end, :both]) }
+    # Every tri-state display_on value passed the old filter, so availability
+    # only ever meant "active".
+    scope :available, -> { active }
     scope :store_credit, -> { where(type: 'Spree::PaymentMethod::StoreCredit') }
 
+    # Customer-facing methods vs backoffice-only ones (manual check entry,
+    # internal wire transfers). The backoffice always sees every method.
+    scope :storefront_visible, -> { where(storefront_visible: true) }
+    scope :admin_only, -> { where(storefront_visible: false) }
+
+    # Real column, so admin clients filter it directly — no ransacker needed.
+    self.whitelisted_ransackable_attributes = %w[storefront_visible]
+
     after_initialize :set_name, if: :new_record?
 
     validates :name, presence: true
-    validates :store, presence: true, unless: -> { Spree::Config[:disable_store_presence_validation] }
+    validates_store_uniqueness :name
+    validates :store, presence: true
+    validates :storefront_visible, inclusion: { in: [true, false] }
     normalizes :name, with: ->(value) { value&.to_s&.squish&.presence }
 
     belongs_to :store, class_name: 'Spree::Store'
@@ -38,6 +70,10 @@ module Spree
       Spree.payment_methods
     end
 
+    # Gateways predate `registers_subclasses_via` and expose their registry as
+    # `providers`; declaring it keeps subclass resolution to a single rule.
+    registers_subclasses_via { providers }
+
     def provider_class
       raise ::NotImplementedError, 'You must implement provider_class method for this gateway.'
     end
@@ -59,6 +95,20 @@ module Spree
       nil
     end
 
+    # Risk codes the gateway can derive from a payment source — the address and
+    # card-verification check results the provider recorded when the source was
+    # created. Payment assigns them at creation when the gateway response path
+    # did not supply any, so session-created payments still feed
+    # +Spree::Payment.risky+ and order risk analysis.
+    #
+    # Override in gateway subclasses that store check results on their sources.
+    #
+    # @param _source [Spree::PaymentSource, Spree::CreditCard]
+    # @return [Hash, nil] +{ avs_response:, cvv_response_code: }+ or nil
+    def risk_codes_for(_source)
+      nil
+    end
+
     # Creates a payment session via the provider.
     # Override in gateway subclasses to implement provider-specific session creation.
     def create_payment_session(order:, amount: nil, external_data: {})
@@ -176,15 +226,44 @@ module Spree
       []
     end
 
+    # The method's own choice when it has one, otherwise the store's. A legacy
+    # auto_capture of true is still honored for installs that set it before
+    # capture_method existed and have not run the migration task.
+    #
+    # auto_capture false is NOT read as manual: it only ever recorded "not at
+    # checkout" and could not distinguish dispatch from staff collection, so
+    # the store decides — the same rows the migration deliberately leaves
+    # empty. Reading it as manual would exclude those payments from dispatch
+    # capture while still letting the goods go out.
+    #
+    # @return [String] one of Spree::CaptureMethod::CAPTURE_METHODS
+    def resolved_capture_method
+      return capture_method if capture_method.present?
+      return 'checkout' if auto_capture
+
+      store_preference(:capture_method).presence || Spree::CaptureMethod::DEFAULT_CAPTURE_METHOD
+    end
+
+    # @deprecated Use #capture_at_checkout?; removed in 6.1. Deliberately does
+    #   not warn — it runs on every payment and would flood the logs.
     def auto_capture?
-      auto_capture.nil? ? Spree::Config[:auto_capture] : auto_capture
+      capture_at_checkout?
     end
 
     def supports?(_source)
       true
     end
 
-    def cancel(_response)
+    # Settles a payment for a canceled order. A gateway releases what it never
+    # drew on; what it does with money already taken depends on `refund:`,
+    # which is false when the operator asked to keep it — an adapter that
+    # cannot void a captured charge must then leave it alone rather than
+    # refunding anyway.
+    #
+    # @param _response [String] the gateway's authorization for the payment
+    # @param _payment [Spree::Payment, nil]
+    # @param refund [Boolean] whether money already captured may be returned
+    def cancel(_response, _payment = nil, refund: true)
       raise ::NotImplementedError, 'You must implement cancel method for this payment method.'
     end
 
@@ -210,6 +289,24 @@ module Spree
       end
     end
 
+    # @deprecated Use {#storefront_visible?}; removed in 6.1.
+    def available_on_front_end?
+      Spree::Deprecation.warn('Spree::PaymentMethod#available_on_front_end? is deprecated and will be removed in Spree 6.1. Use #storefront_visible? instead.')
+      storefront_visible?
+    end
+
+    # @deprecated Use {#storefront_visible}; removed in 6.1.
+    def display_on
+      Spree::Deprecation.warn('Spree::PaymentMethod#display_on is deprecated and will be removed in Spree 6.1. Use #storefront_visible instead.')
+      storefront_visible? ? 'both' : 'back_end'
+    end
+
+    # @deprecated Use {#storefront_visible=}; removed in 6.1.
+    def display_on=(value)
+      Spree::Deprecation.warn('Spree::PaymentMethod#display_on= is deprecated and will be removed in Spree 6.1. Use #storefront_visible= instead.')
+      self.storefront_visible = value.to_s != 'back_end'
+    end
+
     protected
 
     def public_preference_keys

data/app/models/spree/payment_session.rb

@@ -4,65 +4,34 @@ module Spree
 
     acts_as_paranoid
 
-    include Spree::Metafields
+    include Spree::HasCustomFields
 
     self.event_prefix = 'payment_session'
 
     publishes_lifecycle_events
 
-    belongs_to :order, class_name: 'Spree::Order'
+    belongs_to :order, class_name: 'Spree::Order', optional: true
+    belongs_to :cart, class_name: 'Spree::Cart', optional: true, inverse_of: :payment_sessions
     belongs_to :payment_method, class_name: 'Spree::PaymentMethod'
-    belongs_to :customer, class_name: Spree.user_class.to_s, optional: true
+    belongs_to :customer, class_name: Spree.customer_class.to_s, optional: true
 
     has_one :payment, class_name: 'Spree::Payment',
             foreign_key: :response_code,
             primary_key: :external_id
 
-    validates :order, :payment_method, :external_id, :status, :currency, presence: true
+    validates :external_id, :status, :currency, presence: true
+    validate :exactly_one_owner
     validates :external_id, uniqueness: { scope: [:order_id, :payment_method_id] }
     validates :amount, presence: true, numericality: { greater_than: 0 }
 
-    state_machine :status, initial: :pending do
-      state :pending
-      state :processing
-      state :completed
-      state :failed
-      state :canceled
-      state :expired
-
-      event :process do
-        transition pending: :processing
-      end
-
-      event :complete do
-        transition [:pending, :processing] => :completed
-      end
-
-      event :fail do
-        transition [:pending, :processing] => :failed
-      end
-
-      event :cancel do
-        transition [:pending, :processing] => :canceled
-      end
-
-      event :expire do
-        transition [:pending, :processing] => :expired
-      end
-
-      after_transition to: :processing, do: :publish_processing_event
-      after_transition to: :completed, do: :publish_completed_event
-      after_transition to: :failed, do: :publish_failed_event
-      after_transition to: :canceled, do: :publish_canceled_event
-      after_transition to: :expired, do: :publish_expired_event
-    end
+    include Spree::PaymentSessionTransitions
 
     scope :not_expired, -> { where('expires_at IS NULL OR expires_at > ?', Time.current) }
     scope :active, -> { not_expired.where(status: %w[pending processing]) }
 
     before_validation :set_defaults_from_order, on: :create
 
-    delegate :store, to: :order
+    delegate :store, to: :owner
 
     def amount_in_cents
       money.cents
@@ -83,24 +52,152 @@ module Spree
     # @param metadata [Hash] gateway-specific metadata
     # @return [Spree::Payment] the payment record
     def find_or_create_payment!(metadata = {})
-      return payment if payment.present?
-
-      order.payments.find_or_create_by!(
+      # An unsaved session has no identity to key a payment to, and nothing
+      # has settled against it.
+      return unless persisted?
+
+      # Session payments carry no Spree-side source unless the gateway builds
+      # one, so the requirement is skipped on every load, not just at creation
+      # — a later capture webhook transitions the same row and would otherwise
+      # fail source validation.
+      return skip_source_requirement(payment) if payment.present?
+
+      # Keyed on the gateway's own identifier alone. Never on the amount: a
+      # session whose amount moved is still the same intent, and a second row
+      # for it would both double the order's money and collide with the unique
+      # index on (owner, payment_method, response_code).
+      created = owner.payments.find_or_create_by!(
         payment_method: payment_method,
-        response_code: external_id,
-      ) do |p|
-        p.amount = amount
-        p.skip_source_requirement = true
+        response_code: external_id
+      ) do |new_payment|
+        new_payment.amount = amount
+        new_payment.skip_source_requirement = true
+        new_payment.source = payment_source_for_settlement
+        apply_settlement_metadata(new_payment, metadata)
       end
+
+      skip_source_requirement(created)
     rescue ActiveRecord::RecordNotUnique
-      order.payments.find_by!(
-        payment_method: payment_method,
-        response_code: external_id
+      # The webhook and the customer's synchronous return race by design;
+      # whoever loses the insert finds the row the winner created.
+      skip_source_requirement(
+        owner.payments.find_by!(
+          payment_method: payment_method,
+          response_code: external_id
+        )
       )
     end
 
+    # The payment source to attach when the payment row is first created.
+    # Gateways holding the instrument (a card, a mandate) build one here so
+    # the payment shows a brand and last four digits; those with nothing to
+    # represent return nil and the payment stands on its own.
+    #
+    # Called inside the settlement lock, so it must not perform provider I/O
+    # — warm anything it needs in +prepare_for_settlement!+.
+    #
+    # @return [Spree::PaymentSource, nil]
+    def payment_source_for_settlement
+      nil
+    end
+
+    # Records gateway-specific detail on the new payment. Overridden by
+    # gateways that carry references worth keeping (a charge id, a mandate).
+    #
+    # @param payment [Spree::Payment] unsaved
+    # @param metadata [Hash] whatever the settling caller passed
+    # @return [void]
+    def apply_settlement_metadata(payment, metadata)
+      payment.metadata.merge!(metadata.stringify_keys) if metadata.present?
+    end
+
+    # Fetches whatever settlement will need from the provider, so a caller
+    # that settles inside a lock (the webhook path) holds it across no
+    # provider I/O. Gateway session subclasses override; no-op by default.
+    #
+    # @return [Spree::PaymentSession] self
+    def prepare_for_settlement!
+      self
+    end
+
+    # The one place a session settles its payment — used by both routes a
+    # settled session is noticed on (the storefront confirm call and the
+    # gateway webhook), so the two can never drift apart.
+    #
+    # Serialized on the owner's row: the two routes can race, and the
+    # completed? guard alone is check-then-act — two concurrent settlements
+    # would each record a capture event, doubling captured_amount. The lock
+    # wraps only the local settlement, never gateway I/O — callers fetch
+    # provider data first (the confirm path as it verifies the session, the
+    # webhook path via prepare_for_settlement!) — and nests as a no-op inside
+    # HandleWebhook's own owner lock.
+    #
+    # @param captured [Boolean] whether the gateway reports the funds as
+    #   captured; false means authorized only, so the payment pends
+    # @param metadata [Hash] gateway-specific metadata for payment creation
+    # @return [Spree::Payment, nil]
+    def settle_payment!(captured:, metadata: {})
+      owner.with_lock do
+        settled_payment = find_or_create_payment!(metadata)
+
+        if settled_payment.present?
+          # DB-state recheck, deliberately not a reload — the payment may have
+          # been cached on this instance before the lock (a concurrent
+          # settlement could have completed it), but reload would discard
+          # in-memory state like skip_source_requirement.
+          already_completed = settled_payment.completed? ||
+                              Spree::Payment.where(id: settled_payment.id, status: 'completed').exists?
+
+          settled_payment.confirm!(captured: captured) unless already_completed
+        end
+
+        settled_payment
+      end
+    end
+
+    # @return [Spree::Cart, Spree::Order, nil]
+    def owner
+      order || cart
+    end
+
+    # Bridge for legacy callers assigning +current_order+ (now a Spree::Cart)
+    # to the order association — routes carts to the cart FK instead.
+    def order=(record)
+      if record.is_a?(Spree::Cart)
+        self.cart = record
+        super(nil)
+      else
+        super
+      end
+    end
+
+    # Assigns the owning record to the matching association (cart or order),
+    # clearing the other one. Lets gateways stay owner-agnostic.
+    #
+    # @param record [Spree::Cart, Spree::Order]
+    def owner=(record)
+      if record.is_a?(Spree::Cart)
+        self.cart = record
+        self.order = nil
+      else
+        self.order = record
+        self.cart = nil
+      end
+    end
+
     private
 
+    # Only for payments with no Spree-side source — a gateway that does record
+    # one (Stripe's card sources) leaves it untouched.
+    def skip_source_requirement(payment_record)
+      payment_record.skip_source_requirement = true if payment_record&.source.blank?
+      payment_record
+    end
+
+    def exactly_one_owner
+      errors.add(:base, :exactly_one_of_cart_or_order, message: Spree.t('errors.messages.exactly_one_of_cart_or_order')) unless [order, cart].compact.one?
+    end
+
     def publish_processing_event
       publish_event('payment_session.processing')
     end
@@ -122,11 +219,11 @@ module Spree
     end
 
     def set_defaults_from_order
-      return unless order
+      return unless owner
 
-      self.amount ||= order.total_minus_store_credits if amount.blank? || amount.zero?
-      self.currency ||= order.currency
-      self.customer ||= order.user
+      self.amount ||= owner.total_minus_store_credits if amount.blank? || amount.zero?
+      self.currency ||= owner.currency
+      self.customer ||= owner.customer
     end
   end
 end

data/app/models/spree/payment_setup_session.rb

@@ -4,53 +4,20 @@ module Spree
 
     acts_as_paranoid
 
-    include Spree::Metafields
+    include Spree::HasCustomFields
 
     self.event_prefix = 'payment_setup_session'
 
     publishes_lifecycle_events
 
-    belongs_to :customer, class_name: Spree.user_class.to_s, optional: true
+    belongs_to :customer, class_name: Spree.customer_class.to_s, optional: true
     belongs_to :payment_method, class_name: 'Spree::PaymentMethod'
     belongs_to :payment_source, polymorphic: true, optional: true
 
-    validates :payment_method, :status, presence: true
+    validates :status, presence: true
     validates :external_id, uniqueness: { scope: :payment_method_id }, allow_nil: true
 
-    state_machine :status, initial: :pending do
-      state :pending
-      state :processing
-      state :completed
-      state :failed
-      state :canceled
-      state :expired
-
-      event :process do
-        transition pending: :processing
-      end
-
-      event :complete do
-        transition [:pending, :processing] => :completed
-      end
-
-      event :fail do
-        transition [:pending, :processing] => :failed
-      end
-
-      event :cancel do
-        transition [:pending, :processing] => :canceled
-      end
-
-      event :expire do
-        transition [:pending, :processing] => :expired
-      end
-
-      after_transition to: :processing, do: :publish_processing_event
-      after_transition to: :completed, do: :publish_completed_event
-      after_transition to: :failed, do: :publish_failed_event
-      after_transition to: :canceled, do: :publish_canceled_event
-      after_transition to: :expired, do: :publish_expired_event
-    end
+    include Spree::PaymentSessionTransitions
 
     scope :active, -> { where(status: %w[pending processing]) }
 

data/app/models/spree/payment_source.rb

@@ -3,7 +3,7 @@ module Spree
   class PaymentSource < Spree.base_class
     has_prefix_id :ps
 
-    include Spree::Metafields
+    include Spree::HasCustomFields
     include Spree::Metadata
     include Spree::PaymentSourceConcern
 
@@ -11,7 +11,8 @@ module Spree
     # Associations
     #
     belongs_to :payment_method, class_name: 'Spree::PaymentMethod'
-    belongs_to :user, class_name: Spree.user_class.to_s, optional: true
+    belongs_to :customer, class_name: Spree.customer_class.to_s, optional: true
+    include Spree::DeprecatedCustomerAlias
 
     #
     # Validations
@@ -26,9 +27,9 @@ module Spree
     # Returns the gateway customer for the user.
     # @return [Spree::GatewayCustomer]
     def gateway_customer
-      return if user.blank?
+      return if customer.blank?
 
-      payment_method.gateway_customers.find_by(user: user)
+      payment_method.gateway_customers.find_by(customer: customer)
     end
   end
 end

data/app/models/spree/payment_split.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Spree
+  # One child order's share of one payment made against an order group.
+  #
+  # A grouped checkout takes a single charge — the customer authorised one
+  # amount, and creating N gateway charges would change what they agreed to.
+  # The per-seller bookkeeping is these rows: each child order's authorised,
+  # captured and refunded share of that one payment.
+  #
+  # Durable rather than computed on read, because the shares stop being
+  # proportional the moment anything partial happens: one seller ships and is
+  # captured while another has not, one child is refunded and its siblings are
+  # not. A proportion recomputed from current totals cannot express that
+  # history; a row can.
+  #
+  # Every payment on the group gets its own set of rows — the gateway charge,
+  # the store credit, the gift card — so a child's shares across all of them
+  # sum to that child's total, whatever the customer paid with.
+  class PaymentSplit < Spree.base_class
+    has_prefix_id :paysp
+
+    #
+    # Associations
+    #
+    belongs_to :payment, class_name: 'Spree::Payment', inverse_of: :payment_splits
+    belongs_to :order, class_name: 'Spree::Order', inverse_of: :payment_splits
+
+    #
+    # Validations
+    #
+    validates :authorized_amount, :captured_amount, :refunded_amount, numericality: true
+    validates :currency, presence: true
+    validates :order_id, uniqueness: { scope: [:payment_id, *spree_base_uniqueness_scope] }
+
+    #
+    # Scopes
+    #
+    self.whitelisted_ransackable_attributes = %w[currency authorized_amount captured_amount refunded_amount]
+    self.whitelisted_ransackable_associations = %w[payment order]
+
+    extend Spree::DisplayMoney
+    money_methods :authorized_amount, :captured_amount, :refunded_amount, :claimed_amount,
+                  :net_captured_amount, :refundable_amount
+
+    # This child's reported position: what it has captured, less the refunds a
+    # subscriber has already written back to {#refunded_amount}.
+    #
+    # The *reported* figure, which is what makes it right for reading — a
+    # seller's earnings, an order's payment total — and wrong for bounding a
+    # refund, since the column trails the rows. Reach for {#refundable_amount}
+    # before moving money.
+    #
+    # @return [BigDecimal]
+    def net_captured_amount
+      captured_amount - refunded_amount
+    end
+
+    # The most this child order can still be given back from this payment.
+    #
+    # The same quantity as {#net_captured_amount} counted from the refund rows
+    # instead of the denormalized column, because that column is written by a
+    # subscriber after the fact: two refunds landing together would each read a
+    # share that still looked unrefunded. {Spree::Refunds::Create} bounds every
+    # refund by this under the payment's lock.
+    #
+    # @return [BigDecimal]
+    def refundable_amount
+      already_refunded = Spree::Refund.where(payment_id: payment_id, order_id: order_id).sum(:amount)
+      captured_amount - already_refunded
+    end
+
+    # What is left of this share for a parcel to draw on.
+    #
+    # Counts money already taken and money another parcel has reserved but not
+    # yet drawn, so two dispatching at once cannot both reach for the same
+    # amount.
+    #
+    # @return [BigDecimal]
+    def undrawn_amount
+      authorized_amount - captured_amount - claimed_amount
+    end
+
+    # @return [Boolean] whether a charge for this share is still in flight —
+    #   reserved by a parcel, and not yet confirmed by the gateway
+    def capture_in_flight?
+      claimed_amount.positive?
+    end
+  end
+end