spree_stripe 1.8.1 → 6.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd7ae7fd51255dec03bb8bd709ceae4e9440dc8a61d64a62086fc91950937af0
-  data.tar.gz: 7f0c2798878679d21e6337269912e5a5be047c57348255b4536cf2f4de23ed87
+  metadata.gz: a2f387f965ec98112170fb6b256195aa241b444a05ffa58cf949224df588fc0a
+  data.tar.gz: 3e2361e3d0f42ce61575c14ecf8455623b2b6d4b4e6f6c20bd9d13956451fbf4
 SHA512:
-  metadata.gz: edb953569b6fdab13d67ef13128f9edd29e2ce85a5a06f5ae7d1a4a2019dcf8a47aa313452474388ae983e2ccaacbbd8f9003dd8070ba34215fc5464a522fd1f
-  data.tar.gz: 77c47bb3f2d62f3ef0b6cbc48430dc834d6921c1a495aa293b7f3f8c82f25f17703c3a2cc0c3e7522d59e3008fedd5781bb3e9aeafb0d2183e0cf15d6e43cd8e
+  metadata.gz: 21b868b04229b49ac1af09d0deeb1d967cf1e81132d78e1c578dea15e188b7c924f25a9c9fe8fb5377bc0835825b81591dae2f7e8be8d004fbf0fd9e846d406c
+  data.tar.gz: d7e6fe6db6ec611c1e5ae928be04f23330455357cfa99b9f9c809b7916a615c676b0c2b3c8f1ad02fcc0134d9469ca66b8ab466d34c413a08ad71b63194c8568

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Vendo Sp. z o.o., Vendo Connect Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,126 +1,63 @@
-<p align="center">
-  <a href="https://spreecommerce.org">
-    <img alt="Spree Commerce x Stripe integration" src="https://vendo-production-res.cloudinary.com/image/upload/w_2000/q_auto/v1742930549/docs/github/Spree_Commerce_open-source_eCommerce_Stripe_payments_integration_-_Github_xlrcn8.jpg">
-  </a>
-
 # Spree Stripe
 
-This is the official Stripe payment gateway extension for [Spree Commerce](https://spreecommerce.org) [open-source eCommerce platform](https://spreecommerce.org/). 
-
-This Stripe integration is bundled in the [Spree Starter](https://github.com/spree/spree_starter/) for your development convenience. 
-
-Or you could follow the [installation instructions](https://spreecommerce.org/docs/integrations/payments/stripe).
-
-If you like what you see, consider giving this repo a GitHub star :star:
-
-Thank you for supporting Spree open-source :heart:
-
-> [!TIP]
-> Looking for a [Stripe Connect integration](#looking-for-a-stripe-connect-integration-for-spree) for Spree? It's available with the [Enterprise Edition](https://spreecommerce.org/spree-commerce-version-comparison-community-edition-vs-enterprise-edition/).
-
-## Features
-
-- Support for quick checkout using Apple Pay, Google Pay, Stripe Link
-- Support for 3D Secure and other security standards
-- Support for off-session payments
-- Support for Storefront API integration (see the API docs [here](https://spreecommerce.org/docs/api-reference/storefront/stripe)).
-- Accept payments in over 130 currencies
-- Accept Credit Cards, Apple Pay, Google Pay, and more
-- Accept SEPA Direct Debit payments
-- Accept iDEAL payments
-- Accept SOFORT payments
-- Accept Bancontact payments
-- Accept Alipay payments
-- Accept WeChat Pay payments
-- Accept Afterpay, Klarna, Affirm, and more
-
-## What's new?
-
-### Installment (BNPL) payments indicator on PDP (Product Detail Page)
-
-![Spree_x_Stripe_-_BNPL_Installment_payments_Product_Card_PDP_Product_Detail_Page](https://vendo-production-res.cloudinary.com/image/upload/w_2000/q_auto/v1742983146/docs/github/Spree_x_Stripe_-_BNPL_Installment_payments_Product_Card_PDP_Product_Detail_Page_amhfkw.jpg)
-
-### Quick payment options on the cart (Apple Pay, Google Pay, Link)
-
-![Apple_Pay_Google_Pay_Link_-_Quick_payment_options_on_the_cart](https://vendo-production-res.cloudinary.com/image/upload/w_2000/q_auto/v1742930027/docs/github/Spree_x_Stripe_-_Apple_Pay_Google_Pay_Link_-_Quick_payment_options_on_the_cart_aw45x9.jpg)
-
-### Quick payments bypassing checkout 1st step (Apple Pay, Google Pay, Link)
-
-![Apple_Pay_Google_Pay_Link_-_Quick_payments_bypassing_checkout](https://vendo-production-res.cloudinary.com/image/upload/w_2000/q_auto/v1742930027/docs/github/Spree_x_Stripe_-_Apple_Pay_Google_Pay_Link_-_Quick_payments_bypassing_checkout_on_Cart_n6gbh6.jpg)
+Official [Stripe](https://stripe.com) payment gateway for
+[Spree Commerce](https://spreecommerce.org), built on Spree's payment session
+API.
 
-### Various payment options on the payment step (cards, BNPL, Apple Pay, Google Pay, Link)
-
-![Quick payments bypassing checkout 1st step (Apple Pay, Google_Pay, Link)](https://vendo-production-res.cloudinary.com/image/upload/w_2000/q_auto/v1742930027/docs/github/Spree_x_Stripe_-_Apple_Pay_Google_Pay_Link_-_Checkout_payment_step_rxxnr9.jpg)
+Supports card payments plus Klarna, Affirm, Afterpay, Alipay, iDEAL, Link,
+SEPA Direct Debit, Przelewy24 and bank transfers, along with Apple Pay and
+Google Pay quick checkout. Customers can save payment methods for later use
+through setup sessions.
 
 ## Installation
 
-1. Add this extension to your Gemfile with this line:
-
-    ```ruby
-    bundle add spree_stripe
-    ```
-
-2. Run the install generator
-
-    ```ruby
-    bundle exec rails g spree_stripe:install
-    ```
-
-3. Restart your server
-
-  If your server was running, restart it so that it can find the assets properly.
-
-  This Stripe integration is also bundled in the [Spree Starter](https://github.com/spree/spree_starter/) for your development convenience.
+Add the gem to your `Gemfile`:
 
-## Developing
+```ruby
+gem 'spree_stripe'
+```
 
-1. Create a dummy app
+Then run `bundle install`. The gateway registers itself — there is nothing to
+generate and no migrations to run.
 
-    ```bash
-    bundle update
-    bundle exec rake test_app
-    ```
+## Configuration
 
-2. Add your new code
-3. Run tests
+Create a Stripe payment method in the admin dashboard and enter your
+publishable and secret keys. Everything else is automatic:
 
-    ```bash
-    bundle exec rspec
-    ```
+- The webhook endpoint is registered with Stripe on save, and its signing
+  secret is stored on the payment method.
+- Your storefront domains are registered with Stripe so Apple Pay and Google
+  Pay can offer themselves at checkout.
 
-When testing your applications integration with this extension you may use it's factories.
-Simply add this require statement to your spec_helper:
+Set `STRIPE_SIGNING_SECRET` to verify webhooks forwarded by the Stripe CLI
+during local development.
 
-```ruby
-require 'spree_stripe/factories'
-```
+## Upgrading from spree_stripe 1.x
 
-## Releasing a new version
+Signing secrets used to live in their own tables. Move them onto the payment
+method with:
 
-```shell
-bundle exec gem bump -p -t
-bundle exec gem release
+```bash
+bundle exec rake spree:upgrade:migrate_stripe_webhook_keys
 ```
 
-For more options please see [gem-release README](https://github.com/svenfuchs/gem-release)
+This runs as part of `rake spree:upgrade`. Until it does, gateways carrying a
+pre-6.0 webhook endpoint will reject incoming webhooks.
 
-## Contributing
+Applications still using the Rails storefront checkout, the legacy
+`stripe_event` webhook path, or Stripe Tax should complete the payment session
+migration before upgrading — those paths ship only in the 1.x series.
 
-If you'd like to contribute, please take a look at the
-[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
-pull request.
+## Testing
 
-Copyright (c) 2026 [Vendo Connect Inc.](https://getvendo.com), released under [MIT](https://github.com/spree/spree_stripe/blob/main/LICENSE).
+The suite runs offline against recorded VCR cassettes:
 
-## Looking for a Stripe Connect integration for Spree?
-
-Spree Commerce [Enterprise Edition](https://spreecommerce.org/spree-commerce-version-comparison-community-edition-vs-enterprise-edition/) comes with a fully automated Stripe Connect integration for a [multi-vendor marketplace use case](https://spreecommerce.org/marketplace-ecommerce/):
-
-- Automated split payments between marketplace and vendors
-- Support for multiple payment methods including cards and digital wallets
-- Configurable marketplace fees and commission structures
-- Automated payouts to vendors
-- Comprehensive transaction reporting
-- Built-in fraud prevention tools
+```bash
+bundle exec rake test_app   # once
+bundle exec rspec
+```
 
-Feel free to [reach out](https://spreecommerce.org/get-started/) to learn more.
+Set `RECORD_VCR=1` with real Stripe test credentials to record new
+interactions. Note that renaming a `:vcr`-tagged example changes its cassette
+path, so it will re-record rather than reuse the old file.

data/Rakefile

@@ -1,24 +1,15 @@
-require 'bundler'
-Bundler::GemHelper.install_tasks
-
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
 require 'rspec/core/rake_task'
-require 'spree/testing_support/extension_rake'
+require 'spree/testing_support/common_rake'
 
 RSpec::Core::RakeTask.new
 
-task :default do
-  if Dir['spec/dummy'].empty?
-    Rake::Task[:test_app].invoke
-    Dir.chdir('../../')
-  end
-  Rake::Task[:spec].invoke
-end
+task default: :spec
 
-desc 'Generates a dummy app for testing'
+desc "Generates a dummy app for testing"
 task :test_app do
   ENV['LIB_NAME'] = 'spree_stripe'
-  Rake::Task['extension:test_app'].execute(
-    install_storefront: true,
-    install_admin: true
-  )
+  Rake::Task['common:test_app'].invoke
 end

data/app/jobs/spree_stripe/base_job.rb

@@ -1,5 +1,5 @@
 module SpreeStripe
   class BaseJob < Spree::BaseJob
-    queue_as SpreeStripe.queue
+    queue_as { SpreeStripe.queue }
   end
 end

data/app/jobs/spree_stripe/create_webhook_endpoint_job.rb

@@ -1,7 +1,22 @@
 module SpreeStripe
   class CreateWebhookEndpointJob < BaseJob
-    def perform(payment_method_id)
-      Spree::PaymentMethod.find(payment_method_id).create_webhook_endpoint
+    # @param connect [Boolean] true registers the connected-accounts endpoint,
+    #   which a marketplace holds alongside its payment one
+    def perform(payment_method_id, connect: false)
+      # Both endpoints store their credentials in the one serialised
+      # `preferences` column, so concurrent jobs would drop each other's
+      # signing secret. Locked on load because `with_lock` refuses a record
+      # with unsaved changes, and reading a preference populates its default.
+      Spree::PaymentMethod.transaction do
+        payment_method = Spree::PaymentMethod.lock.find_by(id: payment_method_id)
+        next if payment_method.blank?
+
+        if connect
+          payment_method.create_connect_webhook_endpoint
+        else
+          payment_method.create_webhook_endpoint
+        end
+      end
     end
   end
 end

data/app/models/spree/payment_sessions/stripe.rb

@@ -2,7 +2,6 @@ module Spree
   class PaymentSessions::Stripe < PaymentSession
     delegate :api_options, to: :payment_method
 
-    # Duck-type interface consumed by the CompleteOrder and CreatePayment services
     def stripe_id
       external_id
     end
@@ -31,23 +30,58 @@ module Spree
     end
 
     def successful?
-      stripe_payment_intent.status == 'succeeded'
+      payment_method.payment_intent_successful?(stripe_payment_intent)
     end
 
     def charge_not_required?
       payment_method.payment_intent_charge_not_required?(stripe_payment_intent)
     end
 
-    def find_or_create_payment!(metadata = {})
-      return unless persisted?
-      return payment if payment.present?
+    # Warms everything settlement reads from Stripe — the intent, its charge,
+    # and the gateway customer a card source needs — so the webhook path's
+    # locked settlement does no Stripe I/O.
+    def prepare_for_settlement!
+      stripe_charge
+      payment_method.fetch_or_create_customer(order: owner) if owner&.customer
+      self
+    end
+
+    # Core creates the payment; Stripe only says what instrument it was paid
+    # with. The charge and customer are already warmed by
+    # +prepare_for_settlement!+, so this does no Stripe I/O inside the lock.
+    #
+    # @return [Spree::PaymentSource, nil]
+    def payment_source_for_settlement
+      charge = stripe_charge
+
+      if charge.present?
+        SpreeStripe::CreateSource.new(
+          owner: owner,
+          stripe_payment_method_details: charge.payment_method_details,
+          stripe_payment_method_id: charge.payment_method,
+          stripe_billing_details: charge.billing_details,
+          gateway: payment_method
+        ).call
+      elsif charge_not_required?
+        # Bank transfers settle with no charge object, so the instrument has
+        # to come off the intent instead.
+        intent = stripe_payment_intent
+
+        SpreeStripe::CreateSource.new(
+          owner: owner,
+          stripe_payment_method_details: intent.payment_method,
+          stripe_payment_method_id: intent.payment_method.id,
+          stripe_billing_details: nil,
+          gateway: payment_method
+        ).call
+      end
+    end
 
-      SpreeStripe::CreatePayment.new(
-        order: order,
-        payment_intent: self,
-        gateway: payment_method,
-        amount: amount
-      ).call
+    # Keeps the charge reference alongside whatever the caller passed.
+    def apply_settlement_metadata(payment, metadata)
+      super
+      charge = stripe_charge
+      payment.metadata['stripe_charge_id'] = charge.id if charge.present?
     end
   end
 end

data/app/models/spree_stripe/gateway/connect.rb

@@ -0,0 +1,327 @@
+module SpreeStripe
+  class Gateway < ::Spree::Gateway
+    # The marketplace half of the gateway: paying sellers out of the account
+    # that charged their customers.
+    #
+    # This lives on the gateway rather than in settings of its own because it
+    # is the same Stripe account either way. A marketplace pays sellers from
+    # the money it took, and a transfer signed with a different key than the
+    # charge cannot name that charge as its funding source — so a second copy
+    # of the credentials could only ever drift out of agreement with the first.
+    #
+    # It does need a **second webhook endpoint**, though, and that is not a
+    # detail. Stripe scopes events by where they originate: the marketplace's
+    # own charges on one subscription, everything happening inside a seller's
+    # connected account on another, each with its own signing secret. Adding
+    # the seller events to the payment endpoint would not widen it — it would
+    # switch it over, and the payment webhooks would stop arriving.
+    module Connect
+      extend ActiveSupport::Concern
+
+      # `account.updated` — onboarding is finished when Stripe says the account
+      # can receive transfers, which may be days after the seller stops typing.
+      # `payout.*` — Stripe settling a connected account's balance to its bank,
+      # which is what completes a payout here.
+      CONNECT_EVENTS = %w[
+        account.updated
+        payout.paid
+        payout.failed
+      ].freeze
+
+      included do
+        # As with the payment endpoint's pair: Spree registers the endpoint and
+        # stores what Stripe hands back.
+        preference :connect_webhook_signing_secret, :password, internal: true
+        preference :connect_webhook_endpoint_id, :string, internal: true
+
+        after_commit :create_connect_webhook_endpoint_async, on: %i[create update]
+      end
+
+      # Verifies and acts on one Connect event.
+      #
+      # @param raw_body [String]
+      # @param headers [Hash]
+      # @raise [Spree::PaymentMethod::WebhookSignatureError]
+      def handle_payout_webhook(raw_body, headers)
+        event = verify_connect_webhook_signature(raw_body, headers)
+
+        case event.type
+        when 'account.updated' then handle_account_updated(event)
+        when 'payout.paid' then handle_payout(event, 'paid')
+        when 'payout.failed' then handle_payout(event, 'failed')
+        end
+      end
+
+      # Gives a seller a Stripe Express account and a link to finish setting it
+      # up. Express is the right shape for a marketplace: Stripe collects
+      # identity and bank details on its own pages, so the marketplace never
+      # handles them and inherits Stripe's checks rather than building its own.
+      #
+      # The link is minted per call rather than stored — Stripe's onboarding
+      # links are single-use and short-lived by design.
+      #
+      # @param seller [Spree::Seller]
+      # @param refresh_url [String] where Stripe sends a seller whose link expired
+      # @param return_url [String] where Stripe sends them when they finish
+      # @return [String] the onboarding URL
+      def create_connect_account_link(seller:, refresh_url:, return_url:)
+        # A marketplace usually connects Stripe long before it has any sellers,
+        # and the endpoint is registered when the gateway is saved — so by the
+        # time the first seller onboards there may be nothing listening, and
+        # the `account.updated` that says they can be paid never arrives.
+        # Asked for here because this is the moment it starts to matter.
+        ensure_connect_webhook_endpoint
+
+
+        account_id = payout_account_for(seller) || create_connect_account(seller).tap do |created|
+          seller.set_payout_account_reference(SpreeStripe::PayoutProvider, created)
+        end
+
+        Stripe::AccountLink.create(
+          {
+            account: account_id,
+            refresh_url: refresh_url,
+            return_url: return_url,
+            type: 'account_onboarding'
+          },
+          api_options
+        ).url
+      end
+
+      # Where Stripe sends events originating in sellers' connected accounts.
+      # @return [String, nil]
+      def connect_webhook_url
+        return nil unless store
+
+        "#{store.url_or_custom_domain}/api/v3/webhooks/payouts/#{prefixed_id}"
+      end
+
+      def create_connect_webhook_endpoint
+        SpreeStripe::CreateGatewayWebhooks.new.call(payment_method: self, connect: true)
+      end
+
+      private
+
+      def create_connect_account(seller)
+        params = connect_account_params(seller)
+
+        Stripe::Account.create(
+          params,
+          api_options.merge(idempotency_key: account_idempotency_key(seller, params))
+        ).id
+      end
+
+      def connect_account_params(seller)
+        country_code = seller_country_code(seller)
+
+        params = {
+          country: country_code,
+          email: seller.contact_email,
+          business_profile: { name: seller.name },
+          # What kind of account this is, stated as the three things that
+          # actually differ rather than as a preset: the platform pays Stripe's
+          # fees and owns the dispute relationship, which is what makes this a
+          # marketplace rather than a referral, and the seller gets Stripe's
+          # own hosted dashboard.
+          #
+          # Deliberately no `type: 'express'` beside it. The two are mutually
+          # exclusive — Stripe refuses a request carrying both — and `type` is
+          # deprecated in favour of stating the properties. One consequence
+          # worth knowing: the account reads back as `type: "none"`, so nothing
+          # may branch on that field.
+          #
+          # `requirement_collection` is left unset, which defaults to `stripe`
+          # — Stripe collects what it needs through its hosted onboarding, and
+          # `application` is not even allowed alongside an Express dashboard.
+          controller: {
+            fees: { payer: 'application' },
+            losses: { payments: 'application' },
+            stripe_dashboard: { type: 'express' }
+          },
+          # `card_payments` is never exercised — the marketplace charges on its
+          # own account and only transfers onwards — but Stripe will not grant
+          # `transfers` alone outside the recipient agreement, and refuses
+          # that agreement for a seller in the platform's own country. Abroad
+          # it would be allowed, and is still wrong: a recipient account
+          # cannot receive the cross-border payouts this gem then makes.
+          capabilities: { transfers: { requested: true }, card_payments: { requested: true } },
+          # Spree decides when a seller is settled, so Stripe must not also be
+          # paying their balance out on a schedule of its own — two clocks on
+          # one relationship, and the seller's own setting would be the one
+          # that did nothing.
+          settings: { payouts: { schedule: { interval: 'manual' } } },
+          metadata: { spree_seller_id: seller.id }
+        }
+
+        params
+      end
+
+      # Identifies one request, not the seller.
+      #
+      # Two clicks a second apart must not open two Connect accounts, which is
+      # what an idempotency key is for. But Stripe caches a failed response
+      # against the key for a day, and refuses a retry whose parameters have
+      # changed — so a key that never moves means a seller who hit a bad
+      # request stays broken until tomorrow, and sees a confusing complaint
+      # about mismatched parameters rather than the real problem.
+      #
+      # Keying on the parameters themselves gets both: the identical request
+      # is deduplicated, while a corrected one — a fixed country, an email the
+      # seller has since filled in — is a different request and gets a fresh
+      # attempt rather than yesterday's cached failure.
+      def account_idempotency_key(seller, params)
+        digest = Digest::SHA256.hexdigest(params.to_json)
+
+        "spree-seller-#{seller.prefixed_id}-#{digest[0, 32]}"
+      end
+
+      # Where the seller trades, which decides what currency and bank details
+      # their account can hold. Falls back to the marketplace's own country —
+      # Stripe would otherwise assume it anyway, and assuming it silently is
+      # how a seller ends up with an account no local bank can receive.
+      #
+      # No service agreement is sent with it. A seller abroad needs the
+      # recipient agreement only under Stripe's Global payouts product;
+      # marketplaces on Connect's own cross-border payouts need the standard
+      # one, and sending recipient there would wrongly bar the seller from
+      # taking card payments. Which product a marketplace is on cannot be read
+      # off a country code, so core sends neither and lets Stripe apply the
+      # right default.
+      def seller_country_code(seller)
+        seller.billing_address&.country_code.presence || store.default_country_code
+      end
+
+      # Whether Stripe will let this seller be paid. It can go back to false —
+      # a seller whose documents expire stops being payable, and the ledger
+      # must stop crediting them rather than promise money nothing can send.
+      def handle_account_updated(event)
+        account = event.data.object
+        seller = seller_for_account(account.id)
+        return if seller.nil?
+
+        became_payable = account.payouts_enabled && seller.payouts_enabled_at.nil?
+        seller.update!(payouts_enabled_at: account.payouts_enabled ? (seller.payouts_enabled_at || Time.current) : nil)
+
+        # Anything they earned while unverified is owed and still pending, and
+        # this is the moment it can finally be sent.
+        Spree::SellerTransfers::ExecutePendingJob.perform_later(seller.id) if became_payable
+      end
+
+      # Stripe's payout belongs to a connected account rather than to one of
+      # our settlements, so the seller is found by the account the event names.
+      #
+      # Matching the settlement is by Stripe's own id first. Stripe redelivers
+      # a webhook on any non-2xx or timeout, and without that match a second
+      # delivery would skip the settlement it already completed and land on the
+      # next one still owed — marking an unrelated payout paid.
+      def handle_payout(event, status)
+        object = event.data.object
+        seller = seller_for_account(event.account)
+        return if seller.nil?
+
+        payout = find_payout(seller, object)
+        return if payout.nil?
+
+        if status == 'paid'
+          # A redelivery of a settlement already completed changes nothing.
+          return if payout.completed?
+
+          Spree.seller_payout_complete_workflow.call(seller_payout: payout, reference: object.id)
+        else
+          # Answered even on a completed settlement. A bank can return a payout
+          # days after it was paid, and the money is back in the seller's
+          # balance whether or not our books had moved on — left alone, the
+          # ledger reports a seller settled while Stripe still holds their
+          # earnings. Failing it releases them for the next sweep to send again.
+          payout.fail!
+        end
+      end
+
+      # Which seller Stripe is talking about. A uniquely indexed read of the
+      # account reference, scoped to this store's own sellers.
+      #
+      # Filed under this gem's own key rather than the store's configured
+      # payout provider: Stripe issued the account, so Stripe is what it
+      # belongs to, and a store still settling by hand must still be able to
+      # onboard sellers to Connect.
+      def seller_for_account(account_id)
+        return if account_id.blank?
+
+        Spree::Seller.with_payout_account(store, SpreeStripe::PayoutProvider, account_id).first
+      end
+
+      # @return [String, nil] the Connect account this seller already holds
+      def payout_account_for(seller)
+        seller.payout_account_reference(SpreeStripe::PayoutProvider)
+      end
+
+      # By Stripe's own id alone. Spree creates the payout, so it stored that
+      # id when it did — an event naming an id we hold no settlement for is
+      # about a payout somebody made outside Spree, and guessing which of our
+      # settlements it meant would complete the wrong one.
+      # By Stripe's id first, then by the one we sent with the request.
+      #
+      # The reference is normally stored the moment the payout is created, but
+      # not when the answer to that call was lost — which is exactly the case
+      # that most needs the webhook, since nothing else will tell the operator
+      # whether the money moved. Stripe echoes our metadata back, so the id we
+      # sent identifies the row when the id it assigned is not on file.
+      def find_payout(seller, object)
+        by_reference = seller.seller_payouts.find_by(reference: object.id)
+        return by_reference if by_reference
+
+        # A Stripe object raises for a key it does not carry rather than
+        # answering nil, and an older payout has no metadata at all.
+        return nil unless object.respond_to?(:metadata)
+
+        payout_id = object.metadata['spree_seller_payout_id']
+        return nil if payout_id.blank?
+
+        seller.seller_payouts.find_by(id: payout_id, reference: nil)
+      end
+
+      def verify_connect_webhook_signature(raw_body, headers)
+        signature = headers['HTTP_STRIPE_SIGNATURE']
+
+        connect_webhook_signing_secrets.each do |secret|
+          return Stripe::Webhook.construct_event(raw_body, signature, secret)
+        rescue Stripe::SignatureVerificationError
+          next
+        rescue JSON::ParserError
+          raise Spree::PaymentMethod::WebhookSignatureError, 'Malformed webhook payload'
+        end
+
+        raise Spree::PaymentMethod::WebhookSignatureError, 'Invalid webhook signature'
+      end
+
+      # Development only, matching the payment endpoint: the Stripe CLI signs
+      # forwarded events with its own secret rather than the endpoint's.
+      def connect_webhook_signing_secrets
+        secrets = [preferred_connect_webhook_signing_secret]
+        secrets << ENV['STRIPE_CONNECT_SIGNING_SECRET'] if Rails.env.development?
+        secrets.select(&:present?)
+      end
+
+      # The stored secret is the loop guard, as on the payment endpoint —
+      # registration writes it back through `update!`, which re-runs this.
+      #
+      # Deliberately not gated on the store having sellers. The ordinary setup
+      # order is to connect Stripe first and invite sellers afterwards, and
+      # nothing about creating a seller saves the gateway — so that guard meant
+      # the endpoint was never registered at all, and `account.updated` never
+      # arrived to say who could be paid.
+      def ensure_connect_webhook_endpoint
+        return if preferred_connect_webhook_signing_secret.present?
+
+        SpreeStripe::CreateWebhookEndpointJob.perform_later(id, connect: true)
+      end
+
+      def create_connect_webhook_endpoint_async
+        return if only_webhook_registration_changed?
+        return if preferred_connect_webhook_signing_secret.present? && !stripe_secret_key_changed?
+
+        SpreeStripe::CreateWebhookEndpointJob.perform_later(id, connect: true)
+      end
+    end
+  end
+end