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.

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.rb
index 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 Spree
name
end
+ # 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.rb
index 9b00a7418a..7d9d3bdfee 100644
--- a/spree/core/app/models/spree/seller.rb
+++ b/spree/core/app/models/spree/seller.rb
@@ -18,6 +18,9 @@ module Spree
include Spree::Metadata
include Spree::MemoizedData
include Spree::SanitizableRichText
+ # The seller's account with whichever provider pays them — see
+ # #payout_account_reference.
+ include Spree::HasExternalReferences
MEMOIZED_METHODS = %w[onboarding_requirements onboarding_progress products_count returns_location].freeze
@@ -230,6 +233,36 @@ module Spree
earned - settled
end
+ # 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 Spree
payouts_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.rb
index 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_reference
end
end
diff --git a/spree/core/spec/models/spree/seller_spec.rb b/spree/core/spec/models/spree/seller_spec.rb
index 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 do
expect(seller.resolved_minimum_payout_amount).to eq(25)
end
end
+ # 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
+ end
end
diff --git a/spree/providers/stripe/app/models/spree_stripe/gateway/connect.rb b/spree/providers/stripe/app/models/spree_stripe/gateway/connect.rb
index 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 SpreeStripe
end
end
+ # 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).first
diff --git a/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb b/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb
index 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?