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.

Make connecting a payout account part of the checklist

Damian Legawieced620dae32d4
diff --git a/spree/api/app/controllers/spree/api/v3/seller/onboarding_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/onboarding_controller.rb
index cb38e92868..d20dc6b206 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/onboarding_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/onboarding_controller.rb
@@ -33,6 +33,33 @@ module Spree
render json: onboarding_payload
end
+ # POST /api/v3/seller/onboarding/payout_account
+ #
+ # A fresh link to wherever the provider collects what it needs before
+ # it will pay this seller. Minted per request rather than rendered
+ # with the checklist, because these links are short-lived and
+ # single-use — one made while drawing a page is often dead by the
+ # time the seller clicks it.
+ #
+ # The panel says where to come back to. Core does not know the
+ # panel's routes, and a marketplace may host it anywhere.
+ def payout_account
+ provider = current_store.payout_provider_instance
+ url = provider.onboarding_url(
+ current_seller,
+ refresh_url: params.require(:refresh_url),
+ return_url: params.require(:return_url)
+ )
+
+ # No link means there is nowhere to send them — an operator paying
+ # by hand collects these details themselves.
+ return head :no_content if url.blank?
+
+ render json: { url: url }
+ rescue Spree::Core::GatewayError => e
+ render_service_error(e.message)
+ end
+
protected
def read_actions
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index c800efe0af..e8bed8870c 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -781,6 +781,10 @@ Spree::Core::Engine.add_routes do
# Singular: the checklist is always `current_seller`'s.
resource :onboarding, only: [:show], controller: 'onboarding' do
post :submit_for_review
+ # A fresh link to the payout provider's own onboarding. A POST
+ # because asking for one creates the account at the provider if the
+ # seller has none.
+ post :payout_account
end
resources :requirements, only: [] do
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/onboarding_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/onboarding_controller_spec.rb
index c0e3440a02..1d7d467092 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/onboarding_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/onboarding_controller_spec.rb
@@ -92,4 +92,48 @@ RSpec.describe Spree::Api::V3::Seller::OnboardingController, type: :controller d
expect(seller.reload).to be_onboarding
end
end
+
+ describe 'POST #payout_account' do
+ let(:urls) { { refresh_url: 'https://panel/onboarding', return_url: 'https://panel/onboarding?done=1' } }
+
+ # An operator settling by hand collects bank details themselves, so there
+ # is nowhere to send the seller.
+ it 'answers with nothing when the provider hosts no onboarding' do
+ post :payout_account, params: urls, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ end
+
+ context 'with a provider that hosts its own onboarding' do
+ before do
+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:onboarding_url).
+ and_return('https://provider.example/setup/abc')
+ end
+
+ it 'answers with a fresh link' do
+ post :payout_account, params: urls, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['url']).to eq('https://provider.example/setup/abc')
+ end
+
+ # The panel says where to come back to — core does not know its routes.
+ it 'sends the panel’s own return addresses to the provider' do
+ expect_any_instance_of(Spree::PayoutProvider::System).to receive(:onboarding_url).
+ with(anything, hash_including(refresh_url: urls[:refresh_url], return_url: urls[:return_url])).
+ and_return('https://provider.example/setup/abc')
+
+ post :payout_account, params: urls, as: :json
+ end
+
+ it 'reports a provider that refuses rather than raising' do
+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:onboarding_url).
+ and_raise(Spree::Core::GatewayError, 'not configured')
+
+ post :payout_account, params: urls, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+ end
end
diff --git a/spree/core/app/models/spree/payout_provider/base.rb b/spree/core/app/models/spree/payout_provider/base.rb
index b654e63471..8563272845 100644
--- a/spree/core/app/models/spree/payout_provider/base.rb
+++ b/spree/core/app/models/spree/payout_provider/base.rb
@@ -73,6 +73,36 @@ module Spree
false
end
+ # Where a seller goes to give this provider what it needs before it will
+ # pay them — bank details, identity documents, whatever it asks.
+ #
+ # Nil when there is nowhere to send them, which is the built-in
+ # provider's answer: an operator paying by bank transfer collects those
+ # details themselves, so the requirement is met by the operator marking
+ # it so rather than by the seller going anywhere.
+ #
+ # Implementations mint the link per call — hosted onboarding links are
+ # short-lived and single-use by design, so one is never stored.
+ #
+ # @param seller [Spree::Seller]
+ # @param refresh_url [String] where the provider sends a seller whose
+ # link expired before they finished
+ # @param return_url [String] where it sends them when they are done
+ # @return [String, nil]
+ def onboarding_url(_seller, refresh_url:, return_url:)
+ nil
+ end
+
+ # Whether this provider will now accept money for a seller. Asked of the
+ # provider rather than read off the seller, because only the provider
+ # knows — and its answer can change without anything happening in Spree.
+ #
+ # @param seller [Spree::Seller]
+ # @return [Boolean]
+ def onboarded?(seller)
+ !self.class.requires_payout_account? || seller.payouts_enabled?
+ end
+
# Credits a seller for one fulfilled order.
#
# @param seller_transfer [Spree::SellerTransfer]
diff --git a/spree/core/app/models/spree/seller_requirements/payout_account.rb b/spree/core/app/models/spree/seller_requirements/payout_account.rb
new file mode 100644
index 0000000000..03db3eff27
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirements/payout_account.rb
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Spree
+ module SellerRequirements
+ # Somewhere to send the seller their money.
+ #
+ # A checklist row like any other, rather than a card of its own bolted
+ # beside the checklist: whether a marketplace asks this before admitting a
+ # seller is the operator's decision, exactly as it is for a returns address
+ # or a business document. A marketplace paying by hand may not need it at
+ # all, which is why the kind is registered but not provisioned by default.
+ #
+ # What "done" means belongs to the provider, not here. The built-in one
+ # never refuses a seller, so this reads as complete the moment it is asked
+ # — an operator collecting bank details by email has nothing for the seller
+ # to do. A connected provider answers only once it has run its own checks,
+ # which can be days after the seller stops typing.
+ #
+ # The link itself is deliberately not `action_url`. Hosted onboarding links
+ # are short-lived and single-use, so one minted while rendering a checklist
+ # may be dead before the seller clicks it — the panel asks for a fresh one
+ # at the moment of clicking, through the seller API.
+ class PayoutAccount < Spree::SellerRequirement
+ def met_by_seller?(seller)
+ provider_for(seller).onboarded?(seller)
+ end
+
+ private
+
+ def provider_for(seller)
+ (seller.store || store).payout_provider_instance
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 5969e0fb91..de3b57b97e 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -362,6 +362,7 @@ module Spree
Spree::SellerRequirements::BillingAddress,
Spree::SellerRequirements::ReturnsAddress,
Spree::SellerRequirements::MinimumProducts,
+ Spree::SellerRequirements::PayoutAccount,
Spree::SellerRequirements::RequiredCustomFields,
Spree::SellerRequirements::Attestation,
Spree::SellerRequirements::OperatorReview,
diff --git a/spree/core/spec/models/spree/seller_requirements/payout_account_spec.rb b/spree/core/spec/models/spree/seller_requirements/payout_account_spec.rb
new file mode 100644
index 0000000000..95a7d8bc9f
--- /dev/null
+++ b/spree/core/spec/models/spree/seller_requirements/payout_account_spec.rb
@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+RSpec.describe Spree::SellerRequirements::PayoutAccount do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, :approved, store: store) }
+ let(:requirement) { described_class.create!(store: store, name: 'Payout account', required: true) }
+
+ describe '#met_by_seller?' do
+ # An operator paying by bank transfer collects these details themselves,
+ # so there is nothing for the seller to do and nothing to wait for.
+ context 'with the record-only provider' do
+ it 'is met, since the provider never refuses a seller' do
+ expect(requirement).to be_met_by_seller(seller)
+ end
+ end
+
+ context 'with a provider that pays sellers itself' do
+ before do
+ allow(Spree::PayoutProvider::System).to receive(:requires_payout_account?).and_return(true)
+ end
+
+ it 'is unmet until the provider says the seller can be paid' do
+ expect(requirement).not_to be_met_by_seller(seller)
+ end
+
+ it 'is met once the provider has enabled them' do
+ seller.update!(payouts_enabled_at: Time.current)
+
+ expect(requirement).to be_met_by_seller(seller)
+ end
+
+ # A seller whose documents expire stops being payable, and the checklist
+ # should say so rather than reporting a state that has lapsed.
+ it 'falls back to unmet when the provider withdraws the capability' do
+ seller.update!(payouts_enabled_at: Time.current)
+ expect(requirement).to be_met_by_seller(seller)
+
+ seller.update!(payouts_enabled_at: nil)
+
+ expect(requirement).not_to be_met_by_seller(seller.reload)
+ end
+ end
+ end
+
+ # A marketplace settling by hand should not have this forced on it.
+ it 'is registered as a kind an operator may add' do
+ expect(Spree.seller_requirements).to include(described_class)
+ end
+
+ it 'is not one of the defaults a store starts with' do
+ expect(Spree::SellerRequirement::DEFAULT_KINDS).not_to include(described_class.to_s)
+ end
+end
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 4acee799c1..ce5ae3cf74 100644
--- a/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb
+++ b/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb
@@ -47,6 +47,17 @@ module SpreeStripe
store.payment_methods.active.find { |method| method.is_a?(SpreeStripe::Gateway) }
end
+ # Stripe's own hosted onboarding, where the seller gives Stripe their
+ # identity and bank details directly — so the marketplace never handles
+ # them and inherits Stripe's checks rather than building its own.
+ def onboarding_url(seller, refresh_url:, return_url:)
+ gateway_for(seller.store).create_connect_account_link(
+ seller: seller,
+ refresh_url: refresh_url,
+ return_url: return_url
+ )
+ end
+
# Moves one seller's earning to their connected account.
def transfer!(seller_transfer)
seller = seller_transfer.seller