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
Add plan for Spree 6 moving payment gateways to monorepo
Damian Legawiec48048971e45e
diff --git a/docs/plans/6.0-payment-gateways-monorepo.md b/docs/plans/6.0-payment-gateways-monorepo.mdnew file mode 100644index 0000000000..e76f728d96--- /dev/null+++ b/docs/plans/6.0-payment-gateways-monorepo.md@@ -0,0 +1,231 @@+# Payment Gateways in the Monorepo++**Status:** Design Finalized+**Target:** Spree 6.0+**Depends on:** Payment sessions infrastructure (shipped in core), `6.0-multi-vendor-marketplace.md` (Phase 3b consumes the Stripe gem)+**Author:** Damian Legawiec+**Last updated:** 2026-07-20++## Summary++Move the payment-session-compatible gateway code from the standalone+`spree_stripe` and `spree_adyen` repos into the monorepo as two separate,+optional, lockstep-versioned gems: `spree/stripe` (gem `spree_stripe`) and+`spree/adyen` (gem `spree_adyen`). Only the v3 payment-session path comes over+— the gateway class, its session/setup-session models and services, payment+sources, and webhook parsing. Everything serving the classic Rails storefront,+the legacy admin, the legacy webhook engines, and the Storefront API v2 stays+behind in the old repos, which become 5.x maintenance branches.++Why: the gateways are the only real implementations of core's payment-session+contract (`Spree::PaymentMethod#create_payment_session` /+`#parse_webhook_event` / `#complete_payment_session`, `Spree::PaymentSession`+STI), and that contract is still evolving through 6.0. In-repo gateways give+core CI real coverage (today the only in-repo implementation is+`Spree::PaymentSessions::Bogus`), remove the cross-repo version dance on every+contract change, and put the code where contributors and agents can find it.+The 6.0 marketplace plan independently forces Stripe into the monorepo:+`Spree::PayoutProvider::StripeConnect` ships OSS in-repo and needs the+`stripe` SDK, a configured client, and webhook plumbing — keeping the gateway+external would split Stripe integration across two repos.++This amends the 2026-07-15 decision's "likely into `spree/core`" placement:+dedicated gems, not core.++### Competitor context++- **Vendure** bundled Stripe/Braintree/Mollie/PayPal in one in-monorepo+ `@vendure/payments-plugin` (SDKs as optional peerDependencies), then removed+ it in v3.6.0 to a separate community-plugins repo with one package per+ gateway — for community ownership and decoupled releases, *after* the+ handler contract had been stable for years. Their situation doesn't+ transfer: Spree's gateways are first-party (Vendo-maintained) and our+ contract is still moving.+- **Medusa v2** keeps exactly one first-party payment provider in the monorepo+ (`packages/modules/providers/payment-stripe` → `@medusajs/payment-stripe`,+ hard `stripe` dependency, framework peer pinned to the exact matching+ version), down from five in v1; the rest are community plugins. This — the+ strategic gateway in-repo as the contract's reference implementation — is+ the model we're following, extended to Adyen.+- **Solidus** (separate gem per gateway, own repos) and **Saleor** (external+ payment apps) never bundled.+- The one-fat-package model (`spree_payments`) is ruled out: RubyGems has no+ optional dependencies, so a single gem must either hard-depend on every+ gateway SDK or declare none and fail at runtime. Per-gateway gems with their+ own SDK dependency are the Ruby translation of Vendure's optional peer deps.++## Key Decisions (do not deviate without discussion)++1. **Two gems, not core, not one bundle.** `spree/stripe` and `spree/adyen`+ directories, publishing `spree_stripe` and `spree_adyen`. Core keeps only+ the provider-agnostic contract (`Spree::PaymentMethod` session methods,+ `Spree::PaymentSession`/`PaymentSetupSession`, `Spree::GatewayCustomer`,+ `Spree::Payments::HandleWebhook`, the v3 endpoints). No `spree_payments`+ umbrella gem — nothing generic is left for it to own.+2. **Existing gem names and namespaces are kept.** `SpreeStripe::Gateway` and+ `SpreeAdyen::Gateway` stay as-is because `spree_payment_methods.type` and+ `spree_payment_sessions.type` store STI class names — existing+ installations upgrade with no data migration and the same Gemfile line.+ Core's `Spree::Gateway.api_type` already maps these namespaces.+3. **Lockstep versioning with an exact pin.** `s.version = Spree.version`;+ `s.add_dependency 'spree', s.version` (Rails-style) while the+ payment-session contract is hot through 6.0/6.1, to be relaxed to+ `">= #{s.version}"` (the `spree_emails` pattern) once it stabilizes.+ Gateway-only fixes ship as a whole-train patch release.+4. **Optional gems.** The meta `spree` gem does not depend on them; host apps+ opt in via the Gemfile (starter already lists both). The `spree_admin`+ dependency is dropped — 6.0 gateway configuration goes through the Admin+ API / dashboard.+5. **Each gem hard-depends on its own SDK** (`stripe`, currently+ `>= 10.1, < 19`; `adyen-ruby-api-library`, currently `>= 10.3, < 12`).+ SDK constraints live in the gateway gemspec, never in core.+6. **Only the v3 path is ported; `use_legacy_*` toggles are removed.** The+ 6.0 gems ship a single code path. The drop-set (see Design Details) stays+ in the old repos.+7. **`Spree::PayoutProvider::StripeConnect` lives in `spree/stripe`**, next to+ the gateway and the SDK it requires (marketplace plan Phase 3b).+8. **Old repos become 5.x maintenance branches.** Critical fixes only; no new+ feature work outside the monorepo.+9. **Extraction stays cheap by construction.** If a gateway ever moves to+ community ownership (Vendure's endgame), the per-gem structure lets it+ leave as a directory move with names, namespaces, and STI data untouched.+ Folding into core would foreclose this.++## Design Details++### Monorepo layout++```+spree/+ core/ spree_core+ api/ spree_api+ emails/ spree_emails (optional, depends on spree)+ stripe/ spree_stripe (optional, depends on spree + stripe SDK)+ adyen/ spree_adyen (optional, depends on spree + adyen-ruby-api-library)+```++Each gateway gem is a Rails engine following the existing optional-gem shape:+version from `spree/core/lib/spree/core/version.rb`, engine initializer+registering the gateway (`config.spree.payment_methods << SpreeStripe::Gateway`),+migrations installable via `spree:install:migrations`, its own RSpec suite+(VCR + webmock, as in the source repos).++### Keep-set (what moves)++Both source repos already ship the v3 path alongside the legacy one; the port+keeps the v3 half.++**Stripe (~37 files, ~1,700 LOC):**+- `SpreeStripe::Gateway` + `Gateway::PaymentSessions`,+ `Gateway::PaymentSetupSessions`, `Gateway::PaymentIntents` concerns+ (intents are Stripe-side API objects wrapped by the session flow — no+ intent AR model exists)+- `Spree::PaymentSessions::Stripe`, `Spree::PaymentSetupSessions::Stripe`+ (core-table STI subclasses)+- `SpreeStripe::WebhookKey` + `PaymentMethodsWebhookKey` models and their+ migration (`spree_stripe_webhook_keys`, join table) — encrypted signing+ secrets+- Payment sources (Klarna, Affirm, Alipay, iDEAL, Link, SEPA, bank transfer,+ Przelewy24, AfterPay), services (CreatePayment, CreateSource,+ CreatePaymentSession, CreateGatewayWebhooks, RegisterDomain,+ UpdateCustomer, CompleteOrder), presenters, jobs, the `.stripe` scopes on+ `PaymentMethod`/`GatewayCustomer`++**Adyen (~98 files, ~3,400 LOC, of which 60 are one-per-method payment+sources):**+- `SpreeAdyen::Gateway` + session/setup-session concerns, HMAC-validating+ `parse_webhook_event`, management-API auto-configuration (webhook setup,+ HMAC/client key generation, allowed origins)+- `Spree::PaymentSessions::Adyen`, `Spree::PaymentSetupSessions::Adyen`+ (core-table STI subclasses)+- Event processors (authorisation/capture/cancellation), webhook services,+ payment sources, presenters, jobs. Adyen stashes PSP references via+ `Spree::Metafields` on the payment.++### Drop-set (stays in the old repos)++- Classic Rails storefront: all `app/javascript/`, storefront ERB partials,+ checkout/store controller decorators and helpers, redirect/confirm-payment+ controllers, Apple Pay domain-verification file routes+- Legacy webhook paths: the `stripe_event` engine mount + subscriber block and+ its handler services; Adyen's `POST /adyen/webhooks` controller and the+ `config.spree_adyen` event-code → handler registry+- `SpreeAdyen::PaymentSession` standalone model and its+ `spree_adyen_payment_sessions` table + migrations (superseded by the+ core-table `Spree::PaymentSessions::Adyen`)+- Adyen's Storefront API v2 tree (`lib/spree_api_v2/`) and conditional routes+- Assorted AR decorators (order/payment/store/custom_domain/user) tied to the+ legacy flows+- All `use_legacy_*` preferences and both branches of their conditionals++The Stripe Tax calculator (`SpreeStripe::Calculators::StripeTax`) is ported+only if it fits the `6.0-tax-provider.md` direction (see Open Questions).++### Registration and admin surface++Nothing new. Gateways register on `Rails.application.config.spree.payment_methods`+in their engine initializer; `GET /api/v3/admin/payment_methods/types` derives+availability from loaded providers, so "gem in Gemfile" = "type offered in+admin" with no conditional-SDK logic. Webhook endpoints are the core v3 ones+(`/api/v3/webhooks/payments/:payment_method_id`); `Gateway#webhook_url` and+`#parse_webhook_event` already target them.++## Migration Path++1. **Port Stripe** into `spree/stripe` (smaller keep-set; sequenced first+ because marketplace Phase 3b builds `PayoutProvider::StripeConnect` on+ it). Bring the spec suite + cassettes; wire the gem into monorepo CI and+ the release train; add it to the starter/dev-server path mounts.+2. **Port Adyen** into `spree/adyen` the same way.+3. **Marketplace Phase 3b** adds `Spree::PayoutProvider::StripeConnect`+ inside `spree/stripe`.+4. **Old repos flip to maintenance mode**: README banner pointing at the+ monorepo, 5.x branch for critical fixes, no 6.0 release cut from them.+5. **Host apps upgrade** by bumping the gem version — same `gem 'spree_stripe'`+ / `gem 'spree_adyen'` lines, now resolved from the 6.0 release train. No+ STI data migration. Apps still on the legacy storefront/webhook paths must+ complete the v3 migration (the `use_legacy_*` off state) before 6.0, per+ the gems' existing 5.x migration guides.++## Constraints on Current Work++- **No new feature work in the standalone `spree_stripe`/`spree_adyen` repos**+ — critical fixes only. New gateway capability lands in the monorepo port.+- **Don't rename the `SpreeStripe`/`SpreeAdyen` namespaces** anywhere (docs,+ examples, seeds): STI columns depend on them (Key Decision 2).+- Changes to the core payment-session contract+ (`Spree::PaymentMethod` session methods, `Spree::PaymentSession`,+ `Spree::Payments::HandleWebhook`, the v3 session/webhook endpoints) must be+ checked against both gateway implementations — after the port, monorepo CI+ does this; until then, coordinate with the external repos before merging.+- New payment gateways (e.g. `spree_paypal_checkout`) follow this plan's+ shape: own `spree/<provider>` gem, existing name kept if published, lockstep+ version, exact `spree` pin, SDK as the gem's own dependency.+- The `spree` meta gem must not gain a dependency on any gateway gem.++## Open Questions++- **Webhook-key tables → encrypted preferences?** Stripe's two custom tables+ exist to hold per-endpoint signing secrets; they may collapse into encrypted+ preferences on the payment method. Decide during the port — default is to+ keep the tables (smaller diff, proven).+- **Stripe Tax calculator**: port into `spree/stripe`, or drop and revisit as+ a `TaxProvider` under `6.0-tax-provider.md`? Leaning drop-and-revisit.+- **`spree_paypal_checkout` timing**: same treatment, but in-scope for 6.0 or+ after? Not blocking this plan.+- **CI secrets for gateway suites**: the source repos use VCR cassettes+ (offline-safe); confirm no live-credential jobs are needed in monorepo CI.++## References++- `docs/plans/decisions.md` — 2026-07-20 entry (this plan; amends 2026-07-15+ "likely into `spree/core`")+- `docs/plans/6.0-multi-vendor-marketplace.md` — Phase 3b (StripeConnect+ payout provider), OSS/Enterprise boundary+- `docs/plans/6.0-tax-provider.md` — Stripe Tax open question+- Source repos: `spree/spree_stripe`, `spree/spree_adyen`+- Vendure payments extraction: `vendurehq/community-plugins` (v3.6.0 removal+ of `packages/payments-plugin`)+- Medusa v2 provider packaging:+ `medusajs/medusa` → `packages/modules/providers/payment-stripe`+ (`@medusajs/payment-stripe`)