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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.mdindex 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 onestables. The Stripe gem ships no migrations at all — a gateway that thinks itneeds a table should first check whether single-store ownership has removedthe 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 Questionsdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 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 defaultstore, 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 registrydiff --git a/spree/core/app/models/spree/gateway_customer.rb b/spree/core/app/models/spree/gateway_customer.rbindex 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 Spreevalidates :profile_id, presence: truevalidates :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)endenddiff --git a/spree/core/app/models/spree/payment.rb b/spree/core/app/models/spree/payment.rbindex 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_sourceafter_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 Spreeprivate+ # 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_ownererrors.add(:base, Spree.t('errors.messages.exactly_one_of_cart_or_order')) unless [order, cart].compact.one?enddiff --git a/spree/core/app/models/spree/payment_method.rb b/spree/core/app/models/spree/payment_method.rbindex 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 Spreenilend+ # 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.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/payment_spec.rb b/spree/core/spec/models/spree/payment_spec.rbindex 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 doendend+ 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!' docontext 'when payment is pending' dobefore dodiff --git a/spree/providers/stripe/app/models/spree_stripe/gateway.rb b/spree/providers/stripe/app/models/spree_stripe/gateway.rbindex 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 SpreeStripeendend+ # 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.rbdeleted file mode 100644index 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.rbdeleted file mode 100644index 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.rbdeleted file mode 100644index 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.rbindex 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!paymentenddiff --git a/spree/providers/stripe/app/services/spree_stripe/update_customer.rb b/spree/providers/stripe/app/services/spree_stripe/update_customer.rbindex 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 SpreeStripeclass 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.rbindex 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 SpreeStripeRails.application.config.spree.payment_methods << SpreeStripe::GatewaySpree.subscribers << SpreeStripe::CustomerUpdatedSubscriberend-- config.to_prepare do- Dir.glob(Engine.root.join('app/**/*_decorator*.rb')) do |decorator|- require_dependency(decorator)- end- endendenddiff --git a/spree/providers/stripe/spec/models/spree_stripe/gateway_spec.rb b/spree/providers/stripe/spec/models/spree_stripe/gateway_spec.rbindex 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 dolet(: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' doVCR.use_cassette('create_customer') do@@ -805,6 +805,38 @@ RSpec.describe SpreeStripe::Gateway doendend+ 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' dolet(: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.rbindex 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 doexpect(payment.payment_method).to eq gatewayexpect(payment.amount).to eq order.total_minus_store_creditsexpect(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::CreditCardexpect(payment.source.gateway_payment_profile_id).to eq(payment_method_id)@@ -66,7 +66,7 @@ RSpec.describe SpreeStripe::CreatePayment doexpect(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_nilexpect(payment.source).to be_a SpreeStripe::PaymentSources::BankTransferexpect(payment.source.gateway_payment_profile_id).to eq(payment_method_id)