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
Record a seller's payout account where identities live
Damian Legawiec8675d2ced9c4
diff --git a/spree/core/app/models/spree/payout_provider/base.rb b/spree/core/app/models/spree/payout_provider/base.rbindex 571e8b8412..b654e63471 100644--- a/spree/core/app/models/spree/payout_provider/base.rb+++ b/spree/core/app/models/spree/payout_provider/base.rb@@ -41,6 +41,19 @@ module Spreenameend+ # The key a seller's account with this provider is recorded under, as a+ # {Spree::ExternalReference} system.+ #+ # Underscored rather than the class name, because a system key is a+ # lowercase identifier by contract — and where a provider gem also ships+ # a {Spree::Integration}, the convention is that the two agree, so a+ # connector, its references and its settings page name the same thing.+ #+ # @return [String]+ def self.reference_system+ name.demodulize.underscore+ end+# Whether this provider can be selected for a store — an external one# overrides it to require connected credentials.#diff --git a/spree/core/app/models/spree/seller.rb b/spree/core/app/models/spree/seller.rbindex 9b00a7418a..7d9d3bdfee 100644--- a/spree/core/app/models/spree/seller.rb+++ b/spree/core/app/models/spree/seller.rb@@ -18,6 +18,9 @@ module Spreeinclude Spree::Metadatainclude Spree::MemoizedDatainclude Spree::SanitizableRichText+ # The seller's account with whichever provider pays them — see+ # #payout_account_reference.+ include Spree::HasExternalReferencesMEMOIZED_METHODS = %w[onboarding_requirements onboarding_progress products_count returns_location].freeze@@ -230,6 +233,36 @@ module Spreeearned - settledend+ # The seller's account with whichever provider pays them — a Stripe Connect+ # `acct_…`, or whatever a SEPA or PayPal provider issues.+ #+ # Kept as an external reference rather than a column because that is+ # exactly what it is: this seller's identity in somebody else's system.+ # Keying it by the provider means a marketplace that migrates keeps the old+ # account on the record instead of overwriting it, and the reverse lookup a+ # webhook needs — "which seller is acct_123?" — is a uniquely indexed read+ # rather than a scan.+ #+ # @return [String, nil]+ def payout_account_reference+ external_id_for(payout_reference_system)+ end++ # @param account_reference [String, nil] blank forgets the account+ # @return [void]+ def payout_account_reference=(account_reference)+ set_external_id(payout_reference_system, account_reference)+ end++ # Sellers holding an account with the store's payout provider, for the+ # reverse lookup a provider webhook does.+ #+ # @param account_reference [String]+ # @return [ActiveRecord::Relation]+ def self.with_payout_account(store, account_reference)+ store.sellers.with_external_id(store.payout_provider_class.reference_system, account_reference)+ end+# Whether a provider says this seller may be sent money yet.## A marketplace settling offline never asks, so a seller with no account@@ -243,6 +276,15 @@ module Spreepayouts_enabled_at.present?end+ # Which system a payout account reference belongs to. The provider's own+ # key, so a marketplace that changes provider does not read the old+ # account as if it were the new one.+ #+ # @return [String]+ def payout_reference_system+ store.payout_provider_class.reference_system+ end+# What this seller's settlement schedule is, falling back to the store's.## @return [String]diff --git a/spree/core/db/migrate/20260822000003_add_payout_account_to_spree_sellers.rb b/spree/core/db/migrate/20260822000003_add_payout_account_to_spree_sellers.rbindex c5b1c3b521..c029ec7f64 100644--- a/spree/core/db/migrate/20260822000003_add_payout_account_to_spree_sellers.rb+++ b/spree/core/db/migrate/20260822000003_add_payout_account_to_spree_sellers.rb@@ -1,17 +1,11 @@class AddPayoutAccountToSpreeSellers < ActiveRecord::Migration[8.1]def change- # The seller's account with whichever provider pays them, and whether that- # provider says it may yet send money.+ # Whether the provider that pays this seller says it may yet send them+ # money — a Stripe Express account reports `payouts_enabled`, and can+ # withdraw it again when documents expire. Nil until a provider has said.#- # Deliberately provider-agnostic columns rather than `stripe_account_id`:- # the payout provider is pluggable, and a marketplace paying by SEPA batch- # or PayPal has an account reference too. Which provider the reference- # belongs to is the store's payout provider, so it is not repeated here.- add_column :spree_sellers, :payout_account_reference, :string- # Set from the provider's own account status — a Stripe Express account- # says when it is payouts_enabled. Nil until a provider has been asked.+ # The account itself is not a column here: it is the seller's identity in+ # an external system, which is what Spree::ExternalReference records.add_column :spree_sellers, :payouts_enabled_at, :datetime-- add_index :spree_sellers, :payout_account_referenceendenddiff --git a/spree/core/spec/models/spree/seller_spec.rb b/spree/core/spec/models/spree/seller_spec.rbindex 704cbb4641..0f0e9e0ca4 100644--- a/spree/core/spec/models/spree/seller_spec.rb+++ b/spree/core/spec/models/spree/seller_spec.rb@@ -416,4 +416,47 @@ describe Spree::Seller doexpect(seller.resolved_minimum_payout_amount).to eq(25)endend+ # The seller's identity in the system that pays them — recorded where every+ # other external identity is, rather than in a column of its own.+ describe 'the payout account' do+ let(:seller) { create(:seller, :approved, store: @default_store) }++ it 'is stored as an external reference against the store’s provider' do+ seller.payout_account_reference = 'acct_123'++ reference = seller.external_references.reload.first+ expect(reference.system).to eq('system')+ expect(reference.external_id).to eq('acct_123')+ end++ it 'reads back what was written' do+ seller.payout_account_reference = 'acct_123'++ expect(seller.reload.payout_account_reference).to eq('acct_123')+ end++ it 'is nil for a seller who holds no account' do+ expect(seller.payout_account_reference).to be_nil+ end++ it 'forgets the account when blanked' do+ seller.payout_account_reference = 'acct_123'+ seller.payout_account_reference = nil++ expect(seller.reload.payout_account_reference).to be_nil+ end++ # What a provider webhook does: it knows the account, not the seller.+ it 'finds the seller an account belongs to' do+ seller.payout_account_reference = 'acct_123'++ expect(Spree::Seller.with_payout_account(@default_store, 'acct_123')).to contain_exactly(seller)+ end++ it 'does not find a seller in another marketplace' do+ seller.payout_account_reference = 'acct_123'++ expect(Spree::Seller.with_payout_account(create(:store), 'acct_123')).to be_empty+ end+ endenddiff --git a/spree/providers/stripe/app/models/spree_stripe/gateway/connect.rb b/spree/providers/stripe/app/models/spree_stripe/gateway/connect.rbindex ad598204ed..8cfe221cf3 100644--- a/spree/providers/stripe/app/models/spree_stripe/gateway/connect.rb+++ b/spree/providers/stripe/app/models/spree_stripe/gateway/connect.rb@@ -116,7 +116,7 @@ module SpreeStripe# must stop crediting them rather than promise money nothing can send.def handle_account_updated(event)account = event.data.object- seller = store.sellers.find_by(payout_account_reference: account.id)+ seller = seller_for_account(account.id)return if seller.nil?became_payable = account.payouts_enabled && seller.payouts_enabled_at.nil?@@ -136,7 +136,7 @@ module SpreeStripe# next one still owed — marking an unrelated payout paid.def handle_payout(event, status)object = event.data.object- seller = store.sellers.find_by(payout_account_reference: event.account)+ seller = seller_for_account(event.account)return if seller.nil?payout = find_payout(seller, object)@@ -149,6 +149,14 @@ module SpreeStripeendend+ # Which seller Stripe is talking about. A uniquely indexed read of the+ # account reference, scoped to this store's own sellers.+ def seller_for_account(account_id)+ return if account_id.blank?++ Spree::Seller.with_payout_account(store, account_id).first+ end+def find_payout(seller, object)seller.seller_payouts.find_by(reference: object.id) ||seller.seller_payouts.owed.where(currency: object.currency.to_s.upcase).order(:created_at).firstdiff --git a/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb b/spree/providers/stripe/app/models/spree_stripe/payout_provider.rbindex 5cf564adeb..ad6b234190 100644--- a/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb+++ b/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb@@ -23,6 +23,12 @@ module SpreeStripe'Stripe Connect'end+ # Matches the Stripe gateway's own integration key, so a seller's Connect+ # account is filed under the same name the rest of the gem uses.+ def self.reference_system+ 'stripe'+ end+# A seller must hold a connected account before anything can be sent to# them, so core will not credit one who does not.def self.requires_payout_account?