@spree/docs 0.1.232 → 0.1.234

package/dist/developer/core-concepts/commissions.md

@@ -310,13 +310,15 @@ There is **no write path**. Lines are read-only in the API, and correcting a cha
 
 ## What this doesn't do
 
-Commission lines say what the marketplace charged. They don't move money.
+Commission lines say what the marketplace charged. They don't move money, and they don't say what a seller is owed.
 
-> **WARNING:** Open source has **no payout ledger**. Paying sellers means connecting a provider such as Stripe Connect, or building against the commission lines and [payment splits](sellers.md#one-checkout-several-sellers). Scheduled payout runs, refund clawbacks and reconciliation are Enterprise features.
+That is the [payout ledger's](sellers.md#payouts) job: when an order is fulfilled, a seller transfer is written for the sale *less these lines*, and payouts settle those transfers on the seller's schedule — by the built-in provider, which keeps the books and leaves the operator to pay by bank, or by Stripe Connect, which performs the transfer. A commission line is an input to that ledger, never a row in it.
+
+> **NOTE:** Refund clawbacks and netting across settlements, reconciliation and seller tax reporting are Spree Enterprise.
 
 ## Related
 
-- [Sellers](sellers.md) — marketplaces, order splitting and payment splits
+- [Sellers](sellers.md) — marketplaces, order splitting, and the payout ledger commission feeds
 - [Taxes](taxes.md) — the tax vocabulary commission lines share
 - [Fees](fees.md) — buyer-facing charges, which commissions are not
 - [Promotions](promotions.md) — the same rules-and-record split, on the buyer side

package/dist/developer/core-concepts/payments.md

@@ -546,18 +546,22 @@ stateDiagram-v2
 
 With **auto-capture** enabled (default for most gateways), the Payment goes directly from `checkout` → `processing` → `completed`. With **manual capture**, it stops at `pending` until an admin captures it.
 
-#### Order Payment States
+#### Order Payment Status
 
-Each payment update also recalculates the order's `payment_state`:
+Each payment update also recalculates the order's `payment_status`, derived from its payments and refunds against the order total:
 
-| Payment State | Description |
+| Payment status | Description |
 |---------------|-------------|
-| `balance_due` | Payment is required for this order |
-| `failed` | The last payment for the order failed |
-| `credit_owed` | This order has been paid for in excess of its total |
-| `paid` | This order has been paid for in full |
-
-> **WARNING:** You may want to keep tabs on the number of orders with a `payment_state` of `failed`. A sudden increase could indicate a problem with your payment gateway and most likely a serious problem affecting customer satisfaction. Check your payment gateway's dashboard for the most recent transactions if this is happening.
+| `none` | Nothing has been authorized or captured |
+| `authorized` | Approved by the gateway, not yet captured |
+| `partially_paid` | Captured less than the order total |
+| `paid` | Captured payments cover the order total |
+| `partially_refunded` | Refunded in part; the customer has paid something net |
+| `refunded` | Refunds returned everything captured |
+| `overcharged` | Captured more than the order total — the customer is owed the difference |
+| `voided` | The order was canceled and its authorization released |
+
+> **WARNING:** Keep an eye on orders sitting at `authorized` or `partially_paid` long after placement — a sudden increase can indicate a problem with your payment gateway that is affecting customers. Check the gateway's own dashboard for recent transactions.
 
 ## Payment Sources
 

package/dist/developer/core-concepts/sellers.md

@@ -270,11 +270,88 @@ See [Commissions](commissions.md) for rate targeting, the four rule types, per-c
 
 ## Payouts
 
-Spree records what each seller earned and what the marketplace charged: the payment splits say what each seller's share of the money was, and the commission lines say what was deducted.
+Spree keeps a two-level ledger of what each seller is owed, and settles it on a schedule. Whether money actually moves is the payout provider's job; the books are kept either way.
 
-> **WARNING:** **Actually moving money to sellers is not implemented in open source.** There is no payout or transfer ledger here — a seller carries payout *preferences* (how often, and a minimum amount), but nothing acts on them.
-> 
-> Paying vendors means connecting a provider such as Stripe Connect, or building against the payment splits and [commission lines](commissions.md). Scheduled payout runs, refund clawbacks, reconciliation and tax reporting are Enterprise features.
+```mermaid
+flowchart LR
+    F["order.fulfilled"] --> T["SellerTransfer<br/><i>earning</i>"]
+    R["refund.created"] --> RV["SellerTransfer<br/><i>refund_reversal</i>"]
+    T --> P["SellerPayout<br/>swept on the seller's schedule"]
+    RV --> P
+    P --> C["complete<br/>operator, or provider webhook"]
+```
+
+### Transfers — what an order earned
+
+A seller earns on **fulfillment**, not on payment: the marketplace holds the money until the goods ship, and a digital order fulfils immediately so it earns immediately. When `order.fulfilled` fires, a `Spree::SellerTransfer` of kind `earning` is written for the seller's sale less [commission](commissions.md), in the sale's currency.
+
+The amount is payment-source-agnostic — store credit and gift cards are how the customer paid, which is the platform's funding concern, not the seller's.
+
+A refund never edits an earning. `refund.created` writes a second row of kind `refund_reversal` against the same order, so what a seller has earned is always the sum of their transfers, and a reversal that lands after a payout closed falls into the next period rather than rewriting a settlement that already happened.
+
+### Payouts — what was sent
+
+On schedule, a seller's confirmed, unsettled earnings are batched into one `Spree::SellerPayout` per currency and handed to the provider. A payout names exactly which transfers it settled, which is what a seller needs to reconcile a deposit.
+
+Both records share one status set: `pending` → `processing` → `completed`, or `failed` / `unresolved`. **Completing is what debits the balance** — a balance is earnings less *completed* settlements — and nothing completes a payout automatically at creation, because "the money arrived" is a claim about the outside world. An operator running the built-in provider marks it paid once the bank transfer is sent; a connected provider marks it paid when its webhook says so. Either way it publishes `seller_payout.completed`.
+
+`unresolved` is deliberate: a send whose outcome nobody knows keeps its transfers rather than releasing them, since releasing is how the same earnings get sent twice.
+
+### Schedule and thresholds
+
+Each seller settles on their own interval — `daily`, `weekly`, `biweekly`, `monthly`, or `manual` — and only once their balance clears a minimum. Both fall back to the store's defaults (`default_payouts_schedule_interval`, `default_minimum_payout_amount`); below the minimum the balance simply carries forward.
+
+The scheduler is the host app's. Two jobs fan out per seller and the interval logic lives inside them, since a cron expression cannot say "weekly, but from whenever *this* seller was last paid":
+
+| Job | Run it | Does |
+|---|---|---|
+| `Spree::SellerPayouts::SweepDueJob` | daily | settles every seller who is due |
+| `Spree::SellerTransfers::ExecutePendingDueJob` | hourly | retries earnings a provider refused — usually a passing thing |
+
+`spree/spree-starter` ships both entries in `server/config/recurring.yml`. A seller on the `manual` interval is skipped by the sweep and settled by hand instead:
+
+
+```typescript Admin SDK
+// Where the seller stands, one row per currency
+const { data: balances } = await adminClient.sellers.balances('sel_xxx')
+
+// Settle them now, whatever their schedule says
+await adminClient.sellers.settle('sel_xxx')
+
+// The built-in provider: record that the bank transfer went out
+await adminClient.sellerPayouts.complete('spo_xxx', { reference: 'TRN-2026-0912-0042' })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/balances' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/payouts' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/seller_payouts/spo_xxx/complete' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "reference": "TRN-2026-0912-0042" }'
+```
+
+
+`GET /admin/seller_transfers` and `GET /admin/seller_payouts` list the ledger across every seller; the seller panel reads its own through `GET /seller/balances`, `/seller/transfers` and `/seller/payouts`, all read-only — the ledger is written by fulfilment and the sweep, never by the seller.
+
+### Payout providers
+
+A provider is a stateless class registered in `Spree.payout_providers` and chosen per store with the `payout_provider` preference. Core ships one:
+
+| Provider | Moves money? | Completion |
+|---|---|---|
+| `Spree::PayoutProvider::System` (default) | No — keeps the books | The operator marks each payout paid, with the bank reference |
+| Stripe Connect (`spree_stripe`) | Yes — transfers each earning to the seller's connected account as goods ship, tied to the charge that funds it | A Stripe webhook, when the money lands |
+
+The contract is small: `transfer!` credits one earning, `pay!` sends one settlement, `reverse!` takes back part of an earning after a refund, and every call carries an idempotency key derived from the ledger row so a retry finds the movement it already made. Providers that need the seller to hold an account with them answer `requires_payout_account?` and implement `onboarding_url` — which is what the **payout account** [onboarding requirement](#onboarding-requirements) drives. To pay sellers through rails of your own, see [Seller payouts](../providers/payouts.md).
+
+See [Stripe Connect for marketplaces](../../integrations/payments/stripe-connect.md) for the shipped provider.
+
+> **NOTE:** Refund clawbacks and netting across settlements, reconciliation, KYC operations and seller tax reporting (DAC7) are Spree Enterprise.
 
 ## The seller panel
 

package/dist/developer/providers/overview.md

@@ -34,6 +34,7 @@ Every connection point is a documented contract with a default implementation th
 | WMS / 3PL / carriers | Fulfillment provider | [Shipping & WMS](fulfillment.md) |
 | Carrier rate shopping | Delivery rate provider | [Custom delivery rates](../how-to/custom-delivery-rate-provider.md) |
 | PSP | Payment gateway | [Custom payment method](../how-to/custom-payment-method.md) |
+| Seller payouts | Payout provider | [Seller payouts](payouts.md) |
 | Tax engine | Tax provider | [Avalara](../../integrations/tax/avalara.md) |
 | Search | Search provider | [Custom search provider](../how-to/custom-search-provider.md) |
 | Identity provider (SSO) | OpenID Connect | [Identity & SSO](sso.md) |

package/dist/developer/providers/payouts.md

@@ -0,0 +1,327 @@
+---
+title: Seller Payouts
+description: Pay marketplace sellers through your own rails — a bank transfer API, a wallet, another PSP's platform product — by implementing the payout provider contract.
+---
+
+Spree keeps the marketplace's books on its own: what each seller earned as their orders shipped, and what has been settled to them. A **payout provider** is the part that actually moves the money. The built-in one moves nothing and leaves the operator to pay by bank; Stripe Connect moves it through connected accounts. This guide is for the third case — a provider of your own.
+
+Read [how the ledger works](../core-concepts/sellers.md#payouts) first. Everything below assumes the vocabulary there: a *transfer* is one order's earning, a *payout* is a batch of them settled to the seller.
+
+## What a provider decides
+
+Core calls a provider at exactly three moments. Each verb takes the ledger row it is about and returns it:
+
+| Verb | When core calls it | What you do |
+|---|---|---|
+| `transfer!(seller_transfer)` | An order is fulfilled and the seller is payable | Credit the seller's earning — or, if your rails only move money at settlement, mark the row `completed` and do nothing else |
+| `pay!(seller_payout)` | A scheduled sweep or an operator settles a seller | Send the batch. Store the provider's own id in `reference`, and leave the status alone — a payout is completed when the money is confirmed to have landed, not when it was sent |
+| `reverse!(seller_transfer)` | A refund takes back part of an earning | Pull the money back if your rails can. Core writes the reversal row either way, so a provider that cannot claw back implements this as a no-op |
+
+Alongside the verbs, a provider tells core what it needs from sellers before it can pay them:
+
+| Method | Answers |
+|---|---|
+| `self.requires_payout_account?` | Must a seller hold an account with you first? When `true`, core will not credit a seller until they are marked payable |
+| `onboarding_url(seller, refresh_url:, return_url:)` | A fresh hosted link where the seller gives you what you need. Minted per call — these links expire. `nil` when you host nothing |
+| `onboarded?(seller)` | Will you accept money for this seller right now? Ask your API; the answer can change without anything happening in Spree |
+| `onboarding_state(seller)` | Why not yet: `:action` (the seller must do something), `:pending` (you are checking), `:rejected`, or `nil` |
+| `onboarding_message(seller)` | Your own words about what is outstanding. Best-effort and unlocalized |
+
+And three class-level descriptors: `display_name` (what the operator picks in settings), `reference_system` (the key a seller's account is filed under — a lowercase identifier, matching your `Spree::Integration` key if you ship one), and `available_for_store?(store)` (`false` until the store holds credentials for you). Leave `provider_key` alone: it is the full class name, and it is what the ledger's unique index on `(provider, reference)` keys on.
+
+Providers are stateless and built with no arguments. Anything request-specific arrives as a parameter.
+
+## Writing your own
+
+The example below settles sellers by bank transfer through a fictional payments API. It moves money only at payout time, so `transfer!` is pure bookkeeping.
+
+```ruby server/app/models/my_app/payout_provider.rb
+module MyApp
+  class PayoutProvider < Spree::PayoutProvider::Base
+    def self.display_name
+      'Acme Bank Rails'
+    end
+
+    def self.reference_system
+      'acme'
+    end
+
+    def self.requires_payout_account?
+      true
+    end
+
+    def self.available_for_store?(store)
+      store.integrations.active.exists?(type: 'MyApp::AcmeIntegration')
+    end
+
+    def onboarding_url(seller, refresh_url:, return_url:)
+      account_id = seller.payout_account_reference(self.class) ||
+                   client(seller.store).accounts.create(email: seller.contact_email).id.tap do |id|
+                     seller.set_payout_account_reference(self.class, id)
+                   end
+
+      client(seller.store).onboarding_links.create(account: account_id, refresh_url:, return_url:).url
+    rescue Acme::Error => e
+      raise Spree::Core::GatewayError, e.message
+    end
+
+    def onboarded?(seller)
+      account = client(seller.store).accounts.retrieve(seller.payout_account_reference(self.class))
+      account.verified?
+    end
+
+    def transfer!(seller_transfer)
+      seller_transfer.update!(status: 'completed')
+      seller_transfer
+    end
+
+    def pay!(seller_payout)
+      seller = seller_payout.seller
+      transfer = client(seller.store).transfers.create(
+        amount: seller_payout.amount,
+        currency: seller_payout.currency,
+        destination: seller.payout_account_reference(self.class),
+        idempotency_key: idempotency_key(seller_payout)
+      )
+
+      seller_payout.update!(reference: transfer.id)
+      seller_payout
+    rescue Acme::TimeoutError, Acme::ServerError => e
+      raise Spree::Core::AmbiguousGatewayError, e.message
+    rescue Acme::Error => e
+      raise Spree::Core::GatewayError, e.message
+    end
+
+    def reverse!(seller_transfer)
+      seller_transfer.update!(status: 'completed')
+      seller_transfer
+    end
+
+    private
+
+    def client(store)
+      Acme::Client.new(api_key: store.integrations.active.find_by!(type: 'MyApp::AcmeIntegration').preferred_api_key)
+    end
+  end
+end
+```
+
+Credentials come from a [Spree integration](../how-to/custom-delivery-rate-provider.md#1-store-credentials-in-an-integration), never from environment variables — a marketplace may run several stores, and each pays from its own account. The one the provider reads above holds the API key and the secret your webhooks are signed with:
+
+```ruby server/app/models/my_app/acme_integration.rb
+module MyApp
+  class AcmeIntegration < Spree::Integration
+    preference :api_key, :password
+    preference :webhook_secret, :password
+
+    def self.integration_group = 'payments'
+
+    def can_connect?
+      Acme::Client.new(api_key: preferred_api_key).ping
+      true
+    rescue Acme::Error => e
+      self.connection_error_message = e.message
+      false
+    end
+  end
+end
+```
+
+### Register it
+
+```ruby server/config/initializers/spree.rb
+Spree.integrations << 'MyApp::AcmeIntegration'
+Spree.payout_providers << MyApp::PayoutProvider
+```
+
+The operator then picks it under **Settings → Payouts**, which is the store's `payout_provider` preference. The picker is built from the registry, so your provider appears with the two built-in ones and reports whether the store can use it today:
+
+
+```typescript Admin SDK
+const { data: providers } = await adminClient.payoutProviders.list()
+// [{ id: 'MyApp::PayoutProvider', name: 'Acme Bank Rails', available: true,
+//    requires_payout_account: true, default: false }, ...]
+```
+
+```bash cURL
+curl https://your-store.com/api/v3/admin/payout_providers \
+  -H "X-Spree-API-Key: sk_xxx"
+```
+
+
+A store whose configured provider disappears from the registry — a gem removed, a class renamed — silently falls back to the built-in one so the ledger keeps recording. Rename with `def self.provider_key` pinned to the old name if you ever need to, or the rows written under the old name stop matching.
+
+## Errors decide what happens next
+
+Core reads two exceptions, and which one you raise decides whether the money is offered to your API again:
+
+| You raise | What it means | What core does |
+|---|---|---|
+| `Spree::Core::GatewayError` (or any other `StandardError`) | A definite refusal — the money did not move | An earning stays retryable and `SellerTransfers::ExecutePendingDueJob` asks again on its hourly run. A payout is marked `failed` and its earnings are released for the next sweep |
+| `Spree::Core::AmbiguousGatewayError` | Nobody knows — a timeout, a 5xx, an idempotency conflict | The row is parked as `unresolved`. Nothing automatic touches it again; an operator resolves it against your books, or your webhook does |
+
+Get this right. Raising a plain error on a timeout is how the same settlement is sent twice: the payout is failed, its earnings go back on the pile, and the next sweep batches them into a new payout with a new idempotency key — one your provider has never seen.
+
+## Idempotency
+
+Every call carries `idempotency_key(record)` — `spree-<prefixed id>` of the ledger row. Pass it to your API on every write. A crash between your API answering and Spree committing is retried, and the retry must find the movement it already made rather than make a second.
+
+If your rails have no idempotency keys, look the movement up by that key (or by the row's prefixed id in your own metadata) before creating it.
+
+## Seller accounts
+
+A seller's account with your provider is stored as an [external reference](erp.md#addressing-records-by-your-keys) filed under your `reference_system`, so a marketplace that migrates between providers keeps every account on record:
+
+| Need | Call |
+|---|---|
+| Record the account you opened | `seller.set_payout_account_reference(MyApp::PayoutProvider, 'acct_123')` |
+| Read it back | `seller.payout_account_reference(MyApp::PayoutProvider)` |
+| Find the seller a webhook is about | `Spree::Seller.with_payout_account(store, MyApp::PayoutProvider, 'acct_123').first` |
+
+The reverse lookup is a uniquely indexed read, scoped to the store's own sellers — a webhook naming an account from another store finds nothing.
+
+## Onboarding
+
+When a store's provider requires an account, the operator adds the **Payout account** row to the seller [onboarding checklist](../core-concepts/sellers.md#onboarding-requirements). That row reads your `onboarded?` and `onboarding_state`, and the seller panel's button asks for a link at the moment it is clicked:
+
+
+```typescript Seller SDK
+const { url } = await sellerClient.onboarding.payoutAccount({
+  refresh_url: 'https://sellers.your-store.com/onboarding?refresh=1',
+  return_url: 'https://sellers.your-store.com/onboarding',
+})
+// url is null when the provider hosts no onboarding of its own
+```
+
+```bash cURL
+curl -X POST https://your-store.com/api/v3/seller/onboarding/payout_account \
+  -H "Authorization: Bearer <seller_jwt>" \
+  -H "X-Spree-Seller-Id: sel_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{"refresh_url": "https://sellers.your-store.com/onboarding?refresh=1", "return_url": "https://sellers.your-store.com/onboarding"}'
+```
+
+
+That request lands in your `onboarding_url`. A `Spree::Core::GatewayError` raised there becomes a 422 the panel can show; anything else is a crash.
+
+## Confirming from a webhook
+
+Two things only your provider can tell Spree, and both usually arrive as webhooks: that a seller became payable, and that a payout landed or bounced. The Stripe provider receives them through the shipped `/api/v3/webhooks/payouts/:payment_method_id` route, which works for any provider that is also a payment method and implements `handle_payout_webhook(raw_body, headers)` on its gateway. A standalone provider adds its own endpoint to the host app.
+
+Address it to the integration rather than the store: the integration is what holds the signing secret, and the store follows from it.
+
+```ruby server/config/routes.rb
+Rails.application.routes.draw do
+  post 'webhooks/acme/:integration_id', to: 'acme_webhooks#create'
+
+  mount Spree::Core::Engine, at: '/'
+end
+```
+
+```ruby server/app/controllers/acme_webhooks_controller.rb
+# Events from the payout provider: POST /webhooks/acme/:integration_id
+#
+# Handled inline rather than in a job — marking a seller payable or a payout
+# settled is a couple of database writes — and answered with a 5xx when they
+# fail, so the provider redelivers. A 200 for work that did not happen is a
+# settlement nobody will ever record.
+class AcmeWebhooksController < ActionController::API
+  include ActionController::RateLimiting
+
+  rate_limit to: 120, within: 1.minute, store: Rails.cache, by: -> { request.remote_ip }
+
+  def create
+    integration = Spree::Integration.active.find_by_prefix_id!(params[:integration_id])
+    event = verified_event(integration)
+
+    case event['type']
+    when 'account.updated' then account_updated(integration.store, event['data'])
+    when 'transfer.paid' then payout_settled(integration.store, event['data'], paid: true)
+    when 'transfer.failed' then payout_settled(integration.store, event['data'], paid: false)
+    end
+
+    head :ok
+  rescue Spree::Integration::WebhookSignatureError
+    head :unauthorized
+  rescue ActiveRecord::RecordNotFound
+    head :not_found
+  rescue StandardError => e
+    Rails.error.report(e, source: 'my_app.webhooks.acme')
+    head :internal_server_error
+  end
+
+  private
+
+  # Constant-time comparison against the secret this integration was given.
+  # Anything unsigned or signed for another store is a 401, so a
+  # misconfigured sender notices rather than being silently ignored.
+  def verified_event(integration)
+    expected = OpenSSL::HMAC.hexdigest('SHA256', integration.preferred_webhook_secret.to_s, request.raw_post)
+    given = request.headers['X-Acme-Signature'].to_s
+    raise Spree::Integration::WebhookSignatureError unless ActiveSupport::SecurityUtils.secure_compare(expected, given)
+
+    JSON.parse(request.raw_post)
+  rescue JSON::ParserError
+    raise Spree::Integration::WebhookSignatureError, 'Malformed webhook payload'
+  end
+
+  # The provider knows the account, not the seller. The reverse lookup is a
+  # uniquely indexed read scoped to this store, so an account id from another
+  # tenant finds nothing.
+  def seller_for(store, account_id)
+    Spree::Seller.with_payout_account(store, MyApp::PayoutProvider, account_id).first
+  end
+
+  # Whether the provider will now accept money for this seller. It can go
+  # back to false — expired documents, a closed account — and clearing the
+  # stamp makes Spree hold new earnings instead of promising money nothing
+  # can send. Becoming payable sends whatever they earned while unverified.
+  def account_updated(store, data)
+    seller = seller_for(store, data['account_id'])
+    return if seller.nil?
+
+    verified = data['verified'] == true
+    became_payable = verified && seller.payouts_enabled_at.nil?
+
+    seller.update!(payouts_enabled_at: verified ? (seller.payouts_enabled_at || Time.current) : nil)
+    Spree::SellerTransfers::ExecutePendingJob.perform_later(seller.id) if became_payable
+  end
+
+  # Matched on the reference stored in `pay!`, never on amount or recency: a
+  # redelivered event would otherwise skip the settlement it already completed
+  # and land on the next one owed. The workflow is idempotent against a second
+  # delivery and races safely with an operator marking the same payout paid.
+  def payout_settled(store, data, paid:)
+    seller = seller_for(store, data['account_id'])
+    return if seller.nil?
+
+    payout = seller.seller_payouts.find_by(provider: MyApp::PayoutProvider.provider_key, reference: data['transfer_id'])
+    return if payout.nil? || payout.completed?
+
+    if paid
+      Spree.seller_payout_complete_workflow.call(seller_payout: payout, reference: data['transfer_id'])
+    else
+      payout.fail!
+    end
+  end
+end
+```
+
+`fail!` releases the payout's earnings so the next sweep picks them up again. Completing publishes `seller_payout.completed`, which is what the seller's balance and their panel read.
+
+## What to test
+
+The Stripe provider's spec in the monorepo (`spree/providers/stripe/spec/models/spree_stripe/payout_provider_spec.rb`) is the reference battery. The cases worth copying:
+
+- `pay!` passes the idempotency key and stores the provider's id as `reference`, leaving the status `pending`
+- A timeout raises `AmbiguousGatewayError`, a refusal raises `GatewayError` — the two the ledger tells apart
+- Amounts are sent in the units your API expects (`Spree::Money::Rounding.to_minor_units(amount, currency)` for cents)
+- `onboarded?` asks the API rather than reading the cached stamp
+
+> **NOTE:** Refund clawbacks netted across settlements, reconciliation against provider statements, KYC operations and seller tax reporting (DAC7) are Spree Enterprise. Open source ships the ledger, the contract, and the two providers above.
+
+## Related
+
+- [Sellers — payouts](../core-concepts/sellers.md#payouts) — the ledger, the schedule, and the admin API around it
+- [Commissions](../core-concepts/commissions.md) — what a seller's earning is net of
+- [Stripe Connect for marketplaces](../../integrations/payments/stripe-connect.md) — the shipped provider that moves money

package/dist/integrations/payments/stripe-connect.md

@@ -0,0 +1,98 @@
+---
+title: "Stripe Connect for Marketplaces"
+sidebarTitle: Stripe Connect
+description: "Pay your sellers through Stripe Connect — hosted Express onboarding, a transfer to each seller as their goods ship, and settlements confirmed by webhook."
+---
+
+Stripe Connect is the payout provider that ships with Spree's Stripe integration. You charge customers on your own Stripe account, each seller holds a connected Express account, and Spree moves every seller's share across as their orders ship. Read [how the payout ledger works](../../developer/core-concepts/sellers.md#payouts) first — this page covers only what Stripe adds to it.
+
+## Prerequisites
+
+- A [Stripe payment method](stripe.md) on the store, active, with its keys entered. Connect uses the same account and credentials — there is nothing separate to connect.
+- Connect enabled on that Stripe account (Stripe Dashboard → **Connect** → Get started). Spree creates Express accounts, so pick the platform profile Stripe suggests for marketplaces.
+- Sellers on the store. If you have none yet, [invite one](/user/sellers/onboarding).
+
+## Turn it on
+
+Go to **Settings → Payouts** and choose **Stripe Connect** as the payout provider. The option is only offered once an active Stripe payment method exists on the store. The schedule and minimum on the same page decide when Spree settles each seller.
+
+The same setting through the Admin API:
+
+
+```typescript Admin SDK
+const { data: providers } = await adminClient.payoutProviders.list()
+// find the row with id 'SpreeStripe::PayoutProvider' — `available` says whether this store can use it
+
+await adminClient.store.update({
+  preferred_payout_provider: 'SpreeStripe::PayoutProvider',
+  preferred_default_payouts_schedule_interval: 'weekly',
+  preferred_default_minimum_payout_amount: 50,
+})
+```
+
+```bash cURL
+curl -X PATCH https://your-store.com/api/v3/admin/store \
+  -H "X-Spree-API-Key: sk_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{"preferred_payout_provider": "SpreeStripe::PayoutProvider", "preferred_default_payouts_schedule_interval": "weekly", "preferred_default_minimum_payout_amount": 50}'
+```
+
+
+Then add the **Payout account** row to your [seller requirements](/user/sellers/onboarding) so a seller cannot be approved before Stripe can pay them. Without it a seller is approved, sells, and their earnings sit pending until they connect an account.
+
+## Seller onboarding
+
+A seller connects from their panel. The panel asks Spree for a link, Spree creates an Express account for the seller if they have none and asks Stripe for a hosted onboarding link, and the seller lands on Stripe's own pages to give identity and bank details. Spree never handles either.
+
+The account is created with the platform paying Stripe's fees and owning disputes (what makes this a marketplace), the transfers capability requested, the Express dashboard, and — deliberately — a **manual payout schedule**. Spree decides when a seller is settled, so Stripe must not also be paying their balance out on a clock of its own.
+
+The seller's account id is stored as an external reference on the seller under the `stripe` system, so a marketplace that later changes providers keeps it on record.
+
+Three things are worth knowing about "done":
+
+- **Stripe decides, not the form.** A seller who finished typing may still be under review for days. The onboarding checklist asks Stripe each time it is rendered, and shows the seller one of three states: something to do, being checked, or refused — with Stripe's own reason where it gives one.
+- **`account.updated` is the signal.** When Stripe flips `payouts_enabled`, the webhook stamps the seller payable and immediately sends any earnings that were waiting. It can also flip back — expired documents, a closed account — and Spree then stops crediting the seller rather than promise money nothing can send.
+- **The stamp is a cache.** If the webhook never arrived (a local tunnel that was down, an endpoint not yet registered), the next checklist render asks Stripe directly and corrects it.
+
+## Webhooks
+
+Connect events arrive on a separate endpoint from your payment events, because Stripe scopes them separately: events raised inside sellers' connected accounts come on their own subscription with their own signing secret. Spree registers it with Stripe the first time a seller asks for an onboarding link, at:
+
+```
+https://your-store.com/api/v3/webhooks/payouts/<payment method id>
+```
+
+subscribed to `account.updated`, `payout.paid` and `payout.failed`. The endpoint id and signing secret are stored on the payment method. Nothing to do in production.
+
+For local development Stripe cannot reach your machine, so forward the connected-account events with the Stripe CLI and give Spree the secret it prints:
+
+```bash
+stripe listen --forward-connect-to localhost:3000/api/v3/webhooks/payouts/<payment method id>
+export STRIPE_CONNECT_SIGNING_SECRET=whsec_...
+```
+
+`STRIPE_SIGNING_SECRET` covers the payments endpoint the same way; the two are different secrets.
+
+## How the money moves
+
+**On fulfillment**, Spree records the seller's earning — their sale less commission — and creates a Stripe transfer to their connected account. The transfer names the customer's charge as its `source_transaction`, so it settles when that charge does rather than out of your platform balance: a marketplace should not have to float its sellers. The order number goes on the transfer group, and the ledger row's id on the metadata, so both sides reconcile. A seller who is not payable yet keeps the earning pending; it is sent when they become payable, or on the hourly retry.
+
+**On the schedule**, a sweep batches the seller's confirmed earnings into a payout and asks Stripe — acting as the connected account — to pay the seller's bank. The payout stays **pending** in Spree with Stripe's `po_…` id as its reference until `payout.paid` arrives, which completes it and debits the seller's balance. `payout.failed` marks it failed and releases the earnings for the next sweep.
+
+**On a refund**, Spree writes a reversal row against the seller so the books are right. The Stripe transfer itself is not reversed in open source, and a negative balance is not netted against future earnings — that money operation is Spree Enterprise.
+
+Every Stripe call carries an idempotency key derived from the ledger row, so a retried request finds the movement it already made. When Stripe's answer is lost — a timeout, a 5xx — Spree parks the row as **unresolved** instead of retrying, because the key only protects a retry for as long as Stripe remembers it. Resolve those against the Stripe Dashboard: mark the payout complete with its reference if the money went, or fail it if it did not.
+
+## What sellers see
+
+Their panel shows earnings as transfers, settlements as payouts, and a balance per currency — read-only, since Spree and Stripe write both sides. For the bank side (what Stripe actually paid out, and to which account) they use the Express dashboard Stripe gives every connected account.
+
+## Test mode
+
+Use test keys on the Stripe payment method and everything above runs against Stripe's test environment, including Express onboarding with Stripe's test identity data and simulated `payout.paid` events. Connect must be enabled on the test account too.
+
+## Related
+
+- [Payouts](/user/sellers/payouts) — the operator's view: balances, the queue, marking payouts complete
+- [Seller payouts](../../developer/providers/payouts.md) — the provider contract, if Stripe is not your rails
+- [Stripe payments](stripe.md) — the payment method Connect builds on

package/dist/integrations/payments/stripe.md

@@ -1,12 +1,12 @@
 ---
 title: "Connect Stripe payments to Spree Commerce"
 sidebarTitle: Stripe
-description: "Set up Spree's native Stripe integration to accept cards and alternative payment methods, automate payouts, and power marketplace split payments on Enterprise."
+description: "Set up Spree's native Stripe integration to accept cards and alternative payment methods, and pay marketplace sellers through Stripe Connect."
 ---
 
 Stripe is a widely used payment processor that enables secure and seamless transactions for online businesses. It supports multiple payment methods, automates payouts, and ensures a smooth checkout experience for customers.
 
-> **TIP:** In [Spree Enterprise Edition](https://spreecommerce.org/pricing/), Stripe can also be used to power marketplace payments, enabling automated vendor payouts, split payments, and secure transaction handling.
+> **TIP:** Running a marketplace? The same Stripe account pays your sellers through [Stripe Connect](stripe-connect.md).
 
 ## Installation
 
@@ -119,13 +119,4 @@ See [<u>Settings → Tax</u>](/user/settings/tax) for more on configuring tax ra
 
 ## Stripe Connect for Marketplaces
 
-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 [multi-vendor marketplace use cases](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
-
-Feel free to [reach out](https://spreecommerce.org/get-started/) to learn more.
+Stripe Connect is the payout provider that ships with this integration: each seller onboards to an Express account through Stripe's hosted pages, their share of every order is transferred as it ships, and settlements are confirmed by webhook. Setup and the money flow are on their own page — [Stripe Connect for marketplaces](stripe-connect.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.232",
+  "version": "0.1.234",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",