Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Eliminate the provider's core-model decorators

Damian Legawiecebfaa4903898
diff --git a/docs/plans/6.0-payment-gateways-monorepo.md b/docs/plans/6.0-payment-gateways-monorepo.md
index b42c4dc6d9..f483d4a3e5 100644
--- a/docs/plans/6.0-payment-gateways-monorepo.md
+++ b/docs/plans/6.0-payment-gateways-monorepo.md
@@ -268,6 +268,13 @@ admin" with no conditional-SDK logic. Webhook endpoints are the core v3 ones
tables. The Stripe gem ships no migrations at all — a gateway that thinks it
needs a table should first check whether single-store ownership has removed
the reason.
+- **Providers never decorate core models.** A capability a provider needs from
+ a core model goes through a core interface instead: gateway-derived risk
+ codes through `PaymentMethod#risk_codes_for(source)` (asked by `Payment` at
+ creation), provider-scoped gateway customers through
+ `GatewayCustomer.for_provider`, provider identity through `api_type` and
+ `where(type:)`, and ad-hoc provider data through the `metadata` column
+ directly — `store_accessor` sugar does not justify a decorator.
## Resolved Questions
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index b53027a5eb..968e823e08 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -330,6 +330,38 @@ ships in the OSS Admin API; first-run configures the one store.
Consequences: Admin API code must never assume `current_store` is the default
store, and store-touching cache keys must carry the store id by construction.
Plan: `6.0-store-context-and-first-run-setup.md`.
+## 2026-08-12 — Providers never decorate core models; risk codes become a gateway interface
+
+The Stripe provider shipped with three decorators on core models, and all three
+are gone. A decorator is the extension mechanism of last resort — a first-party
+provider using them licenses every third-party gateway to do the same, and a
+`before_save` on `Spree::Payment` firing forever for one provider's bookkeeping
+is exactly the shape that rots.
+
+What replaced them decides the pattern for Adyen and every gateway after it:
+
+- **AVS/CVV risk codes are a core interface.** The session flow never passes
+ through the gateway response path that normally sets
+ `avs_response`/`cvv_response_code` — the check results live on the payment
+ source, in whatever shape the provider recorded them. Core now asks:
+ `PaymentMethod#risk_codes_for(source)` (nil by default), called by `Payment`
+ once at creation, response-path codes winning. Stripe's implementation
+ translates its pass/fail/unchecked checks from the source's metadata. Core
+ owns when to ask; the gateway owns how to answer. The old callback re-ran on
+ every save; the hook runs at creation only — the sole lost case is a payment
+ gaining a Stripe card source after creation, which nothing does.
+- **Provider-scoped gateway customers are a core scope.**
+ `GatewayCustomer.for_provider(SpreeStripe::Gateway)` replaces the decorated
+ `.stripe` scope; every gateway needs exactly this filter.
+- **The rest was dead or sugar.** The `.stripe`/`stripe?` payment-method
+ decorator had no callers left. `store_accessor :metadata, :stripe_charge_id`
+ was sugar over a hash write, so the service writes
+ `payment.metadata['stripe_charge_id']` directly.
+
+**Consequences:** the provider ships zero decorators and the engine's
+`to_prepare` decorator glob is gone. A provider needing something from a core
+model proposes a core interface, mirroring how delivery providers already work
+(`Spree.delivery_rate_providers`, `Spree.fulfillment_providers`).
## 2026-08-13: Validate hooks are the validation extension surface; no generic model-validation registry
diff --git a/spree/core/app/models/spree/gateway_customer.rb b/spree/core/app/models/spree/gateway_customer.rb
index 964f5a427a..88028d1112 100644
--- a/spree/core/app/models/spree/gateway_customer.rb
+++ b/spree/core/app/models/spree/gateway_customer.rb
@@ -11,6 +11,14 @@ module Spree
validates :profile_id, presence: true
validates :payment_method_id, uniqueness: { scope: :customer_id }
+ # Gateway customers whose payment method is the given provider — gateway
+ # gems use this instead of decorating the model with their own scope.
+ #
+ # @param provider [Class, String] a payment method class, eg. SpreeStripe::Gateway
+ scope :for_provider, ->(provider) {
+ joins(:payment_method).where(Spree::PaymentMethod.table_name => { type: provider.to_s })
+ }
+
encrypts :profile_id, deterministic: true if Rails.configuration.active_record.encryption.include?(:primary_key)
end
end
diff --git a/spree/core/app/models/spree/payment.rb b/spree/core/app/models/spree/payment.rb
index 42046c0998..dce77e284b 100644
--- a/spree/core/app/models/spree/payment.rb
+++ b/spree/core/app/models/spree/payment.rb
@@ -51,6 +51,7 @@ module Spree
#
# Callbacks
+ before_create :assign_risk_codes_from_source
after_save :create_payment_profile, if: :profiles_supported?
# update the order totals, etc.
after_save :update_order, unless: -> { capture_on_dispatch }
@@ -298,6 +299,20 @@ module Spree
private
+ # Session-created payments never pass through the gateway response path
+ # that normally sets these codes, so the gateway gets asked at creation.
+ # Codes already assigned (the response path runs before save) win.
+ def assign_risk_codes_from_source
+ return if source.blank?
+ return if avs_response.present? && cvv_response_code.present?
+
+ codes = payment_method&.risk_codes_for(source)
+ return if codes.blank?
+
+ self.avs_response ||= codes[:avs_response]
+ self.cvv_response_code ||= codes[:cvv_response_code]
+ end
+
def exactly_one_owner
errors.add(:base, Spree.t('errors.messages.exactly_one_of_cart_or_order')) unless [order, cart].compact.one?
end
diff --git a/spree/core/app/models/spree/payment_method.rb b/spree/core/app/models/spree/payment_method.rb
index 5d4447dbe4..ffe6df49c9 100644
--- a/spree/core/app/models/spree/payment_method.rb
+++ b/spree/core/app/models/spree/payment_method.rb
@@ -83,6 +83,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: {})
diff --git a/spree/core/spec/models/spree/gateway_customer_spec.rb b/spree/core/spec/models/spree/gateway_customer_spec.rb
new file mode 100644
index 0000000000..d415c238fc
--- /dev/null
+++ b/spree/core/spec/models/spree/gateway_customer_spec.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Spree::GatewayCustomer, type: :model do
+ let(:store) { @default_store }
+
+ describe '.for_provider' do
+ let(:bogus_method) { create(:payment_method, type: 'Spree::Gateway::Bogus', store: store) }
+ let(:check_method) { create(:payment_method, type: 'Spree::PaymentMethod::Check', store: store) }
+
+ let!(:bogus_customer) { create(:gateway_customer, payment_method: bogus_method) }
+ let!(:check_customer) { create(:gateway_customer, payment_method: check_method) }
+
+ it 'returns only customers of the given provider' do
+ expect(described_class.for_provider(Spree::Gateway::Bogus)).to contain_exactly(bogus_customer)
+ end
+
+ it 'accepts the provider as a string' do
+ expect(described_class.for_provider('Spree::PaymentMethod::Check')).to contain_exactly(check_customer)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/payment_spec.rb b/spree/core/spec/models/spree/payment_spec.rb
index ec94447d63..11be2752c1 100644
--- a/spree/core/spec/models/spree/payment_spec.rb
+++ b/spree/core/spec/models/spree/payment_spec.rb
@@ -565,6 +565,37 @@ describe Spree::Payment, type: :model do
end
end
+ describe 'risk codes from the source (before_create)' do
+ before do
+ allow(gateway).to receive(:risk_codes_for).with(card).and_return(
+ avs_response: 'A', cvv_response_code: 'N'
+ )
+ end
+
+ it 'asks the payment method for risk codes at creation' do
+ payment.save!
+
+ expect(payment.avs_response).to eq('A')
+ expect(payment.cvv_response_code).to eq('N')
+ end
+
+ it 'never overwrites codes the gateway response already set' do
+ payment.avs_response = 'Y'
+ payment.cvv_response_code = 'M'
+ payment.save!
+
+ expect(payment.avs_response).to eq('Y')
+ expect(payment.cvv_response_code).to eq('M')
+ end
+
+ it 'does not ask again on later saves' do
+ payment.save!
+ expect(gateway).not_to receive(:risk_codes_for)
+
+ payment.update!(amount: 4)
+ end
+ end
+
describe '#capture!' do
context 'when payment is pending' do
before do
diff --git a/spree/providers/stripe/app/models/spree_stripe/gateway.rb b/spree/providers/stripe/app/models/spree_stripe/gateway.rb
index 9f14eb2882..5d9f6cd4b9 100644
--- a/spree/providers/stripe/app/models/spree_stripe/gateway.rb
+++ b/spree/providers/stripe/app/models/spree_stripe/gateway.rb
@@ -173,6 +173,31 @@ module SpreeStripe
end
end
+ # Stripe reports address and CVC checks as pass/fail/unchecked on the
+ # payment method; CreateSource stores them in the source's metadata. This
+ # translates them to the AVS/CVV response codes core's risk analysis reads.
+ AVS_CODES = {
+ 'pass' => { 'pass' => 'Y', 'fail' => 'A', 'unchecked' => 'B' },
+ 'fail' => { 'pass' => 'Z', 'fail' => 'N' },
+ 'unchecked' => { 'pass' => 'P', 'unchecked' => 'I' }
+ }.freeze
+
+ CVV_CODES = { 'pass' => 'M', 'fail' => 'N', 'unchecked' => 'P' }.freeze
+
+ # @param source [Spree::PaymentSource, Spree::CreditCard]
+ # @return [Hash, nil]
+ def risk_codes_for(source)
+ return unless source.is_a?(Spree::CreditCard)
+
+ checks = source.metadata[:checks]
+ return if checks.blank?
+
+ {
+ avs_response: AVS_CODES.dig(checks[:address_line1_check], checks[:address_postal_code_check]),
+ cvv_response_code: CVV_CODES[checks[:cvc_check]]
+ }
+ end
+
def create_profile(payment)
gateway_customer = fetch_or_create_customer(order: payment.order)
return if payment.source.blank? || gateway_customer.blank?
diff --git a/spree/providers/stripe/app/models/spree_stripe/gateway_customer_decorator.rb b/spree/providers/stripe/app/models/spree_stripe/gateway_customer_decorator.rb
deleted file mode 100644
index 5b83295e92..0000000000
--- a/spree/providers/stripe/app/models/spree_stripe/gateway_customer_decorator.rb
+++ /dev/null
@@ -1,11 +0,0 @@
-module SpreeStripe
- module GatewayCustomerDecorator
- def self.prepended(base)
- base.scope :stripe, lambda {
- joins(:payment_method).where(Spree::PaymentMethod.table_name => { type: SpreeStripe::Gateway.to_s })
- }
- end
- end
-end
-
-Spree::GatewayCustomer.prepend(SpreeStripe::GatewayCustomerDecorator)
diff --git a/spree/providers/stripe/app/models/spree_stripe/payment_decorator.rb b/spree/providers/stripe/app/models/spree_stripe/payment_decorator.rb
deleted file mode 100644
index 1bdf637cbf..0000000000
--- a/spree/providers/stripe/app/models/spree_stripe/payment_decorator.rb
+++ /dev/null
@@ -1,33 +0,0 @@
-module SpreeStripe
- module PaymentDecorator
- # Stripe reports address/CVC checks as pass/fail/unchecked; Spree stores the
- # equivalent AVS and CVV response codes.
- AVS_CODES = {
- 'pass' => { 'pass' => 'Y', 'fail' => 'A', 'unchecked' => 'B' },
- 'fail' => { 'pass' => 'Z', 'fail' => 'N' },
- 'unchecked' => { 'pass' => 'P', 'unchecked' => 'I' }
- }.freeze unless defined?(AVS_CODES)
-
- CVV_CODES = { 'pass' => 'M', 'fail' => 'N', 'unchecked' => 'P' }.freeze unless defined?(CVV_CODES)
-
- def self.prepended(base)
- base.store_accessor :metadata, :stripe_charge_id
-
- base.before_save :set_cvv_and_avs_response_from_metadata, if: :credit_card_source?
- end
-
- def set_cvv_and_avs_response_from_metadata
- checks = source.metadata[:checks]
- return if checks.blank?
-
- self.avs_response ||= AVS_CODES.dig(checks[:address_line1_check], checks[:address_postal_code_check])
- self.cvv_response_code ||= CVV_CODES[checks[:cvc_check]]
- end
-
- def credit_card_source?
- source.is_a?(Spree::CreditCard)
- end
- end
-end
-
-Spree::Payment.prepend(SpreeStripe::PaymentDecorator)
diff --git a/spree/providers/stripe/app/models/spree_stripe/payment_method_decorator.rb b/spree/providers/stripe/app/models/spree_stripe/payment_method_decorator.rb
deleted file mode 100644
index 4fd0dab4b0..0000000000
--- a/spree/providers/stripe/app/models/spree_stripe/payment_method_decorator.rb
+++ /dev/null
@@ -1,15 +0,0 @@
-module SpreeStripe
- module PaymentMethodDecorator
- STRIPE_TYPE = 'SpreeStripe::Gateway'.freeze unless defined?(STRIPE_TYPE)
-
- def self.prepended(base)
- base.scope :stripe, -> { where(type: STRIPE_TYPE) }
- end
-
- def stripe?
- type == STRIPE_TYPE
- end
- end
-end
-
-Spree::PaymentMethod.prepend(SpreeStripe::PaymentMethodDecorator)
diff --git a/spree/providers/stripe/app/services/spree_stripe/create_payment.rb b/spree/providers/stripe/app/services/spree_stripe/create_payment.rb
index 534d381dac..8af5ba68f1 100644
--- a/spree/providers/stripe/app/services/spree_stripe/create_payment.rb
+++ b/spree/providers/stripe/app/services/spree_stripe/create_payment.rb
@@ -25,7 +25,7 @@ module SpreeStripe
)
payment.source = source if source.present?
- payment.stripe_charge_id = stripe_charge&.id
+ payment.metadata['stripe_charge_id'] = stripe_charge.id if stripe_charge.present?
payment.save!
payment
end
diff --git a/spree/providers/stripe/app/services/spree_stripe/update_customer.rb b/spree/providers/stripe/app/services/spree_stripe/update_customer.rb
index 96fb5d2c7a..5c8271463e 100644
--- a/spree/providers/stripe/app/services/spree_stripe/update_customer.rb
+++ b/spree/providers/stripe/app/services/spree_stripe/update_customer.rb
@@ -3,7 +3,7 @@ module SpreeStripe
class UpdateCustomer
# @param customer [Spree::Customer]
def call(customer:)
- gateway_customers = customer.gateway_customers.stripe
+ gateway_customers = customer.gateway_customers.for_provider(SpreeStripe::Gateway)
return if gateway_customers.empty?
gateway_customers.each do |gateway_customer|
diff --git a/spree/providers/stripe/lib/spree_stripe/engine.rb b/spree/providers/stripe/lib/spree_stripe/engine.rb
index db0dfbbe33..cd795ff5a2 100644
--- a/spree/providers/stripe/lib/spree_stripe/engine.rb
+++ b/spree/providers/stripe/lib/spree_stripe/engine.rb
@@ -17,11 +17,5 @@ module SpreeStripe
Rails.application.config.spree.payment_methods << SpreeStripe::Gateway
Spree.subscribers << SpreeStripe::CustomerUpdatedSubscriber
end
-
- config.to_prepare do
- Dir.glob(Engine.root.join('app/**/*_decorator*.rb')) do |decorator|
- require_dependency(decorator)
- end
- end
end
end
diff --git a/spree/providers/stripe/spec/models/spree_stripe/gateway_spec.rb b/spree/providers/stripe/spec/models/spree_stripe/gateway_spec.rb
index 1deed8af80..8ea0e6409c 100644
--- a/spree/providers/stripe/spec/models/spree_stripe/gateway_spec.rb
+++ b/spree/providers/stripe/spec/models/spree_stripe/gateway_spec.rb
@@ -666,7 +666,7 @@ RSpec.describe SpreeStripe::Gateway do
let(:california_state) { usa_country.states.find_by(abbr: 'CA') || create(:state, name: 'California', abbr: 'CA', country: usa_country) }
let(:new_york_state) { usa_country.states.find_by(abbr: 'NY') || create(:state, name: 'New York', abbr: 'NY', country: usa_country) }
- let(:gateway_customer) { Spree::GatewayCustomer.stripe.last }
+ let(:gateway_customer) { Spree::GatewayCustomer.for_provider(SpreeStripe::Gateway).last }
it 'creates a new Stripe customer and gateway customer record' do
VCR.use_cassette('create_customer') do
@@ -805,6 +805,38 @@ RSpec.describe SpreeStripe::Gateway do
end
end
+ describe '#risk_codes_for' do
+ subject { gateway.risk_codes_for(source) }
+
+ context 'with a credit card carrying Stripe checks' do
+ let(:source) do
+ build(:credit_card, metadata: {
+ checks: {
+ address_line1_check: 'pass',
+ address_postal_code_check: 'fail',
+ cvc_check: 'pass'
+ }
+ })
+ end
+
+ it 'translates them to AVS and CVV response codes' do
+ expect(subject).to eq(avs_response: 'A', cvv_response_code: 'M')
+ end
+ end
+
+ context 'with a credit card without checks' do
+ let(:source) { build(:credit_card) }
+
+ it { is_expected.to be_nil }
+ end
+
+ context 'with a non-card source' do
+ let(:source) { SpreeStripe::PaymentSources::Klarna.new }
+
+ it { is_expected.to be_nil }
+ end
+ end
+
describe 'being a provider' do
let(:provider_methods) { %i[authorize purchase capture void credit] }
diff --git a/spree/providers/stripe/spec/services/spree_stripe/create_payment_spec.rb b/spree/providers/stripe/spec/services/spree_stripe/create_payment_spec.rb
index d3fb78b5f3..b3a367626f 100644
--- a/spree/providers/stripe/spec/services/spree_stripe/create_payment_spec.rb
+++ b/spree/providers/stripe/spec/services/spree_stripe/create_payment_spec.rb
@@ -31,7 +31,7 @@ RSpec.describe SpreeStripe::CreatePayment do
expect(payment.payment_method).to eq gateway
expect(payment.amount).to eq order.total_minus_store_credits
expect(payment.response_code).to eq(payment_intent_id)
- expect(payment.stripe_charge_id).to eq('ch_3QY76s2ESifGlJez0gG0FoF1')
+ expect(payment.metadata['stripe_charge_id']).to eq('ch_3QY76s2ESifGlJez0gG0FoF1')
expect(payment.source).to be_a Spree::CreditCard
expect(payment.source.gateway_payment_profile_id).to eq(payment_method_id)
@@ -66,7 +66,7 @@ RSpec.describe SpreeStripe::CreatePayment do
expect(payment.payment_method).to eq(gateway)
expect(payment.amount).to eq(order.total_minus_store_credits)
expect(payment.response_code).to eq(payment_intent_id)
- expect(payment.stripe_charge_id).to be_nil
+ expect(payment.metadata['stripe_charge_id']).to be_nil
expect(payment.source).to be_a SpreeStripe::PaymentSources::BankTransfer
expect(payment.source.gateway_payment_profile_id).to eq(payment_method_id)