Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

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.md
new file mode 100644
index 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`)