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
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.rbindex 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 Spreerender json: onboarding_payloadend+ # 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+protecteddef read_actionsdiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 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' dopost :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_accountendresources :requirements, only: [] dodiff --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.rbindex 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 dexpect(seller.reload).to be_onboardingendend++ 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+ endenddiff --git a/spree/core/app/models/spree/payout_provider/base.rb b/spree/core/app/models/spree/payout_provider/base.rbindex 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 Spreefalseend+ # 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.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex 5969e0fb91..de3b57b97e 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -362,6 +362,7 @@ module SpreeSpree::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.rbnew file mode 100644index 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+enddiff --git a/spree/providers/stripe/app/models/spree_stripe/payout_provider.rb b/spree/providers/stripe/app/models/spree_stripe/payout_provider.rbindex 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 SpreeStripestore.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