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
Changed the PayPal docs and CLI catalog for the 6.0 gem
Łukasz Adamczykd102fb703abc
diff --git a/.changeset/cli-paypal-released-with-spree.md b/.changeset/cli-paypal-released-with-spree.mdnew file mode 100644index 0000000000..3b2af8bb08--- /dev/null+++ b/.changeset/cli-paypal-released-with-spree.md@@ -0,0 +1,5 @@+---+"@spree/cli": patch+---++`spree add paypal` now pins `spree_paypal_checkout` to the project's Spree version, since PayPal ships with Spree from 6.0. Before, it resolved to the 0.x gem, which does not run on Spree 6.diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdxindex 03167eeb44..50044c23c8 100644--- a/docs/developer/upgrades/5.6-to-6.0.mdx+++ b/docs/developer/upgrades/5.6-to-6.0.mdx@@ -690,6 +690,46 @@ Some payloads changed so that every webhook carries the Store API shape and noth- **`saved_report.*`** no longer includes the author's name.- **Subscribing an endpoint to `customer.password_reset_requested`** needs the permission to manage customers. The staff and seller reset events are still never sent to webhooks.+## PayPal++`spree_paypal_checkout` 0.x does not run on Spree 6.0. PayPal now ships with Spree as a provider gem of the same name, released with Spree and pinned to its version (`spree add paypal` pins it for you). It keeps every stored class name, so existing payment methods, payment sessions and payment sources carry over.++| 0.x | 6.0 |+|---|---|+| Payments whose response code is a PayPal capture ID | Rewritten by the `migrate_paypal_payments` upgrade step: the response code becomes the PayPal order ID, and the capture ID moves to the payment's metadata |+| A Webhook ID field, filled in by hand | The webhook is registered automatically. The `register_paypal_webhooks` upgrade step finds or creates each payment method's webhook, replaces the events of one created by hand under the 0.x guide, and stores its ID |+| `spree_paypal_checkout_orders` table and `SpreePaypalCheckout::Order` | The model is gone. The table stays until you drop it, after `migrate_paypal_payments` has run |+| `use_legacy_api` configuration and the Storefront API v2 `paypal_orders` routes | Gone. Move to payment sessions before upgrading |+| Saved PayPal accounts in the admin | Gone. 0.x never saved an account at PayPal, and charging a picked account failed |+| `Spree::PaymentMethod.paypal_checkout` and `Store#paypal_checkout_gateway` | Gone. Use `Spree::PaymentMethod.where(type: 'SpreePaypalCheckout::Gateway')` |+| Rails storefront assets, importmap, ERB partials and admin views | Gone |+| `NEXT_PUBLIC_PAYPAL_CLIENT_ID` in the storefront | Still read as a fallback. The storefront takes the client ID from the payment session |++Both upgrade steps run as part of `spree upgrade` when the gem is installed, and are skipped when it is not:++- **`migrate_paypal_payments`** gives each PayPal payment taken before the upgrade the 6.0 shape, finding its PayPal order through the payment session that took it or, for the older checkout flow, through `spree_paypal_checkout_orders`. A payment it cannot match is left as it was, counted on the run and logged by ID; refund it in PayPal. It supports a preview.+- **`register_paypal_webhooks`** registers the webhook of every PayPal payment method. Until it runs, payment methods created before the upgrade reject every PayPal notification. Your store must be reachable from the internet.++Drop `spree_paypal_checkout_orders` only after `migrate_paypal_payments` has run. It is the only link from payments of the older checkout flow to their PayPal order. Then update the Next.js storefront to a version that reads the client ID from the payment session, or follow [Building your own storefront](/integrations/payments/paypal#building-your-own-storefront) if you built your own.++### Already on 6.0 before installing the gem++A store that upgraded to 6.0 before adding `spree_paypal_checkout` is already recorded as upgraded, so the dashboard's upgrade page does not list these steps. Run them by name:++<CodeGroup>++```bash Spree CLI (Docker)+spree upgrade --step migrate_paypal_payments+spree upgrade --step register_paypal_webhooks+```++```bash Without Spree CLI+STEP=migrate_paypal_payments bundle exec rake spree:upgrade+STEP=register_paypal_webhooks bundle exec rake spree:upgrade+```++</CodeGroup>+## Removed in 6.0These were deprecated in 5.x and are **gone now** — there is no bridge, so calls raise `NoMethodError`. Most were one-line delegations to a replacement that already exists.diff --git a/docs/images/integrations/paypal/2-setup-form.png b/docs/images/integrations/paypal/2-setup-form.pngdeleted file mode 100644index 54ad81ec68..0000000000Binary files a/docs/images/integrations/paypal/2-setup-form.png and /dev/null differdiff --git a/docs/integrations/payments/paypal.mdx b/docs/integrations/payments/paypal.mdxindex b264387a73..542bfe647d 100644--- a/docs/integrations/payments/paypal.mdx+++ b/docs/integrations/payments/paypal.mdx@@ -1,7 +1,7 @@---title: "Connect PayPal payments to Spree Commerce"sidebarTitle: "PayPal"-description: "Enable Spree's native PayPal integration to accept PayPal, Pay Later (BNPL), Venmo, and guest checkout payments without forcing shoppers to create an account."+description: "Enable Spree's native PayPal integration to accept PayPal, Pay Later (BNPL), Venmo, and guest card payments without forcing shoppers to create an account."---PayPal is a global online payment system that allows your customers to pay using their PayPal balance, linked credit or debit cards, or bank accounts. Spree's native PayPal integration also supports PayPal Pay Later (BNPL), Venmo (US only), and guest checkout — giving shoppers flexibility at the payment step without forcing them to create a PayPal account.@@ -16,13 +16,14 @@ Before you can enable PayPal, it must be installed. To do so, you need to run thspree add paypal```-```bash Without Spree CLI-bundle add spree_paypal_checkout && bin/rails g spree_paypal_checkout:install && bin/rails db:migrate+```ruby Without Spree CLI+# server/Gemfile — use the same version requirement as your `spree` gem, then run `bundle install`+gem 'spree_paypal_checkout', '>= 6.0.0'```</CodeGroup>-The Spree CLI also runs the migrations and restarts the server for you. Without it, restart the server yourself after the commands finish.+The Spree CLI restarts the server for you. Without it, restart the server yourself. The gateway registers itself, so there is nothing to generate and no migrations to run.## Connect PayPal@@ -30,11 +31,7 @@ Sign in to your Spree admin dashboard and navigate to **Settings → Payments**.-Find PayPal under Available Payment Methods and click **Add**.--This will redirect you to the PayPal setup form.--+Find PayPal under Available Payment Methods and click **Add**. This opens the PayPal setup form.To retrieve your credentials:@@ -42,34 +39,21 @@ To retrieve your credentials:2. Navigate to **Apps & Credentials** and make sure you're on the **Live** tab.3. Click into your **Default Application** (or create a new app if none exists).4. Copy the **Client ID** and **Secret** and paste them into the matching fields in Spree.-5. _(Optional but recommended)_ Create a webhook subscription to get a **Webhook ID** — see [Webhook ID](#webhook-id) below.-6. Click **Create** to enable PayPal as a payment method on your store.+5. Click **Create** to enable PayPal as a payment method on your store.-<Note>PayPal has three separate systems that are easy to mix up: **paypal.com** (your live merchant account), **sandbox.paypal.com** (where test users log in to simulate payments or review transactions), and **developer.paypal.com** (the dashboard for API credentials). Developer dashboard access requires a live paypal.com Business account.</Note>+Spree checks the credentials with PayPal when you save. If PayPal refuses them, the form says so — most often because **Test Mode** does not match the credentials: sandbox credentials need Test Mode on, live ones need it off.-### Webhook ID+<Note>PayPal has three separate systems that are easy to mix up: **paypal.com** (your live merchant account), **sandbox.paypal.com** (where test users log in to simulate payments or review transactions), and **developer.paypal.com** (the dashboard for API credentials). Developer dashboard access requires a live paypal.com Business account.</Note>-The Webhook ID lets Spree verify that incoming notifications from PayPal (e.g. payment completed, refund issued) are genuinely from PayPal. This is what allows Spree to reliably finalize orders — including in cases where a shopper closes their browser mid-checkout.+### Webhooks-To generate a Webhook ID:+When you save the payment method, Spree registers a webhook with PayPal for it and stores the webhook's ID — there is nothing to set up by hand. It registers again whenever you change the credentials or Test Mode. Every notification PayPal sends is checked with PayPal before Spree acts on it.-1. From the **Apps & Credentials** page, click into your application.-2. Scroll down to the **Webhooks** section (Live or Sandbox depending on the environment).-3. Click **Add Webhook**.-4. Enter your Spree webhook URL: `https://your-store-url.com/api/v3/webhooks/payments/[payment_method_id]`- - The `payment_method_id` is the prefixed ID visible in the URL when editing your PayPal payment method in Spree (e.g. `/payment_methods/pm_1example23/edit`).-5. Select the event types to subscribe to. At minimum:- - Checkout order approved- - Checkout order completed- - Payment capture completed- - Payment capture refunded- - Payment capture denied-6. Click **Save**. PayPal then displays the **Webhook ID**.-7. Copy the Webhook ID and paste it into the **Webhook ID** field in Spree.+Webhooks tell Spree about money PayPal moves after checkout, such as a capture PayPal held for review that has now completed. They do not complete orders: the order is placed when the shopper approves the payment and your storefront completes it. A shopper who closes the browser right after approving gets no order, and PayPal takes no money.-<Warning>Your Spree store must be publicly reachable from the internet for PayPal to deliver webhooks. Webhooks will silently fail against a localhost or VPN-only URL unless you use a tunnel (e.g. ngrok).</Warning>+<Warning>Your Spree store must be publicly reachable from the internet for PayPal to accept the webhook and deliver notifications. Registration fails against a localhost or VPN-only URL unless you use a tunnel (e.g. ngrok).</Warning>## Additional Settings@@ -82,25 +66,42 @@ You can optionally configure the following settings for your PayPal payment meth- Storefront only- Admin panel only- Both (recommended)-- **Auto Capture**: Decide whether payments should be automatically captured at the time of authorization (recommended), or manually captured later.+- **Capture**: When the money is taken. Leave it empty to follow the store's setting. See [Capturing payments](#capturing-payments).- **Active Status**: Enable or disable the payment method. Inactive methods are hidden from checkout but not removed.-## Storefront Configuration+## Capturing payments++PayPal follows the capture setting of the payment method, or the store's when the method has none:++- **At checkout**: PayPal takes the money when the shopper completes checkout.+- **On dispatch** or **Manually**: PayPal authorizes the payment at checkout, and Spree captures it when the order is dispatched or when staff capture it from the dashboard.-For the PayPal SDK to initialize on the Next.js storefront, set the following environment variable in your storefront's hosting platform or `.env` file:+An authorization does not last forever. PayPal honors it for **3 days**, and a capture can be attempted until **day 29**: a capture on days 4–29 may be declined, and one after day 29 always is. Spree does not renew authorizations, so if you ship later than that, capture at checkout instead. A declined capture is reported with PayPal's reason.-- **`NEXT_PUBLIC_PAYPAL_CLIENT_ID`** — Your PayPal **Client ID** (live or sandbox, depending on the environment). This is the same value you pasted into the Spree admin.+PayPal sometimes holds a capture for review (an eCheck, or a payment PayPal is checking). The payment stays pending in Spree and is completed automatically when PayPal releases the money. A dispatch that captures the payment is refused until then. If PayPal denies the held capture instead, Spree is not told: the order stays placed with a pending payment. Check PayPal for the outcome, and void the payment in Spree.-The `NEXT_PUBLIC_` prefix makes the variable available to client-side code so the PayPal JS SDK can initialize in the browser. The Client ID is safe to expose publicly.+## Storefront-<Note>If this env var isn't set, the PayPal payment option won't render on the storefront even if PayPal is configured in the Spree admin.</Note>+The Next.js storefront shows PayPal's buttons for every PayPal payment method, using the client ID and the capture setting that each checkout's payment session carries. There is nothing to configure.++`NEXT_PUBLIC_PAYPAL_CLIENT_ID` is still read, but only for Spree backends older than 6.0 that do not send the client ID with the session.++### Building your own storefront++If your storefront uses the Store API directly:++1. Create a payment session for the PayPal payment method. Its `external_id` is the PayPal order ID, and its `external_data` holds `client_id` and `intent`.+2. Load the PayPal JS SDK with that `client_id` and with `intent` in lowercase (`capture` or `authorize`). The SDK refuses an order created with a different intent.+3. Render one PayPal button for each of these funding sources, each only when PayPal says the shopper is eligible for it: `paypal`, `paylater`, `venmo` and `card`. Do not use PayPal's all-eligible buttons, and do not add other funding sources: PayPal would also offer payment methods that send the shopper to their bank, which this integration does not support.+4. In `onApprove`, complete the payment session, then complete the cart.+5. If completing the session fails, read the session. If it is still `pending`, PayPal declined the shopper's chosen card or account: call `actions.restart()` so they can choose another in PayPal's window. If it is `failed`, show the error and create a new payment session.## Test ModeIf you'd like to test your checkout flow without processing real payments, PayPal's sandbox is a safe and effective way to simulate transactions. To enable it:1. Tick the **Test Mode** checkbox in the PayPal payment method settings in Spree.-2. Paste your **sandbox** Client ID, Client Secret, and Webhook ID into the fields (these are separate from your live credentials). See [Testing PayPal payments](#testing-paypal-payments) below for a full walkthrough of the sandbox setup, which can be unintuitive the first time through.+2. Paste your **sandbox** Client ID and Client Secret into the fields (these are separate from your live credentials). See [Testing PayPal payments](#testing-paypal-payments) below for a full walkthrough of the sandbox setup, which can be unintuitive the first time through.## Testing PayPal payments@@ -124,27 +125,23 @@ In the developer dashboard, go to **Apps & Credentials** and make sure you're onClick into the **Default Application** — PayPal auto-creates this when your developer account is provisioned.-Copy the **Client ID** and **Secret** and paste them into the PayPal payment method settings in Spree, making sure **Test Mode** is ticked.--### 4. Create a sandbox webhook (optional)--In the same Default Application, scroll to the **Sandbox webhooks** section and follow the steps outlined in [Webhook ID](#webhook-id) above to generate a Webhook ID. Paste it into the **Webhook ID** field in Spree.+Copy the **Client ID** and **Secret** and paste them into the PayPal payment method settings in Spree, making sure **Test Mode** is ticked. Spree registers the sandbox webhook when you save.-### 5. Use sandbox test accounts to check out+### 4. Use sandbox test accounts to check out-To simulate a shopper paying with PayPal, add items to your cart and proceed through checkout on your Spree store. When redirected to **sandbox.paypal.com**, log in using the test **Personal** account credentials found in the developer dashboard under **Testing Tools → Sandbox Accounts**.+To simulate a shopper paying with PayPal, add items to your cart and proceed through checkout on your Spree store. When PayPal's window opens on **sandbox.paypal.com**, log in using the test **Personal** account credentials found in the developer dashboard under **Testing Tools → Sandbox Accounts**.These test accounts are pre-funded with fake money, so you can complete checkout without any real funds being involved.-### 6. View sandbox transactions from the merchant side+### 5. View sandbox transactions from the merchant sideTo see transactions as the merchant, log in to [sandbox.paypal.com](https://sandbox.paypal.com) using the **Business** test account credentials (also found under **Testing Tools → Sandbox Accounts**). You'll see incoming payments, refunds, and any webhooks that have fired.### Common Issues-- **Wrong currency**: make sure the sandbox buyer account's currency matches what your Spree store is charging in, or checkout may fail or behave unexpectedly.+- **Wrong currency**: make sure the sandbox buyer account's currency matches what your Spree store is charging in, or checkout may fail or behave unexpectedly. PayPal is not offered at checkout in a currency PayPal does not support.- **Account flagged by PayPal's anti-fraud system**: new accounts sometimes trigger captcha blocks or temporary login restrictions. Wait 30–60 minutes and try from a different network (e.g. a phone hotspot) if you're persistently blocked.-- **Webhooks not delivering**: double-check that your Spree URL is publicly reachable. PayPal will silently fail to deliver to localhost or VPN-only addresses.+- **Webhooks not delivering**: double-check that your Spree URL is publicly reachable. PayPal refuses to register, or silently fails to deliver to, localhost or VPN-only addresses.## Features@@ -153,6 +150,7 @@ Spree's native PayPal integration supports:- PayPal Checkout — branded PayPal buttons at checkout- PayPal Pay Later (Buy Now, Pay Later) where available- Venmo (US merchants only)-- Guest checkout — customers can pay with a credit or debit card without creating a PayPal account-- Webhook-driven order completion — orders are finalized reliably even if shoppers close their browser mid-checkout+- Guest checkout — customers can pay with a credit or debit card in PayPal's window without creating a PayPal account+- Capture at checkout, on dispatch, or manually, following your capture setting+- Webhooks registered and verified automatically- Sandbox environment for testing prior to going livediff --git a/packages/cli/src/extensions.json b/packages/cli/src/extensions.jsonindex 506c005cd7..c9f1fdf8e4 100644--- a/packages/cli/src/extensions.json+++ b/packages/cli/src/extensions.json@@ -3,7 +3,12 @@"mcp": { "label": "MCP server", "gem": "spree_mcp", "release": "spree" },"opentelemetry": { "label": "OpenTelemetry", "gem": "spree_opentelemetry", "release": "spree" },"stripe": { "label": "Stripe", "gem": "spree_stripe", "release": "spree" },- "paypal_checkout": { "label": "PayPal", "gem": "spree_paypal_checkout", "aliases": ["paypal"] },+ "paypal_checkout": {+ "label": "PayPal",+ "gem": "spree_paypal_checkout",+ "aliases": ["paypal"],+ "release": "spree"+ },"adyen": { "label": "Adyen", "gem": "spree_adyen" },"klaviyo": { "label": "Klaviyo", "gem": "spree_klaviyo" },"avatax_official": {diff --git a/packages/cli/tests/add-extension.test.ts b/packages/cli/tests/add-extension.test.tsindex 6789c49727..8b17385246 100644--- a/packages/cli/tests/add-extension.test.ts+++ b/packages/cli/tests/add-extension.test.ts@@ -154,16 +154,25 @@ describe('addExtension', () => {expect(ejectProject).not.toHaveBeenCalled()})+ // PayPal ships with Spree since 6.0; resolving it unpinned would install the+ // 0.x gem, which does not run on 6.0.+ it('pins PayPal to the project version', async () => {+ await addExtension(ctx(), EXTENSIONS.paypal_checkout, { yes: false })++ expect(commands()).toEqual([+ ['bundle', 'add', 'spree_paypal_checkout', '--version', '>= 6.0.0.rc3'],+ ['bin/rails', 'spree:install:migrations', 'db:migrate'],+ ])+ })+it('adds a gem released on its own unpinned, and runs its install generator when it has one', async () => {- vi.mocked(dockerComposeCapture).mockResolvedValue(- 'SpreePaypalCheckout:\n spree_paypal_checkout:install\n',- )+ vi.mocked(dockerComposeCapture).mockResolvedValue('SpreeAdyen:\n spree_adyen:install\n')- await addExtension(ctx(), EXTENSIONS.paypal_checkout, { yes: false })+ await addExtension(ctx(), EXTENSIONS.adyen, { yes: false })expect(commands()).toEqual([- ['bundle', 'add', 'spree_paypal_checkout'],- ['bin/rails', 'generate', 'spree_paypal_checkout:install'],+ ['bundle', 'add', 'spree_adyen'],+ ['bin/rails', 'generate', 'spree_adyen:install'],['bin/rails', 'spree:install:migrations', 'db:migrate'],])})