Skip to main content
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.

Installation

Before you can enable PayPal, it must be installed. To do so, you need to run the following command:
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

Sign in to your Spree admin dashboard and navigate to Settings → Payments. PayPal listed under Payment providers on the Payments settings page Go to Settings → Payments, find PayPal under Payment providers and click Connect. This opens the PayPal setup form. To retrieve your credentials:
  1. Log in to your PayPal Developer Dashboard.
  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. Click Create to enable PayPal as a payment method on your store.
The PayPal credentials page showing Client ID and Secret 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.
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.

Webhooks

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. 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.
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).

Additional Settings

The PayPal Additional Settings panel after the payment method is created You can optionally configure the following settings for your PayPal payment method:
  • Name: Customize the display name shown for this payment method on the storefront.
  • Display: Choose where PayPal should be available:
    • Storefront only
    • Admin panel only
    • Both (recommended)
  • Capture: When the money is taken. Leave it empty to follow the store’s setting. See Capturing payments.
  • Active Status: Enable or disable the payment method. Inactive methods are hidden from checkout but not removed.

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.
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. 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.

Storefront

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, with intent in lowercase (capture or authorize), and with enable-funding=paylater,venmo. The SDK refuses an order created with a different intent. Without enable-funding, PayPal hides Pay Later outside the US, and Venmo everywhere; with it, each still appears only for shoppers PayPal finds eligible.
  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 Mode

If 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 and Client Secret into the fields (these are separate from your live credentials). See Testing PayPal payments below for a full walkthrough of the sandbox setup, which can be unintuitive the first time through.

Testing PayPal payments

PayPal’s sandbox environment can be confusing because it spans three separate sites and requires both a live account (to access the developer dashboard) and test accounts (to simulate shoppers). This section walks through the full setup.

1. Create a live PayPal Business account

Sign up for a PayPal Business account at paypal.com. This is your real account — you won’t process any real transactions through it, but it’s required in order to access the developer dashboard.
You can skip the bank account linking step during signup — it isn’t required for sandbox testing.

2. Access the PayPal Developer Dashboard

Navigate to developer.paypal.com and log in using your live PayPal Business account credentials.
If you hit a login loop or “incorrect credentials” error, log into paypal.com first, verify your email address, then navigate to the developer dashboard in the same browser session.

3. Get sandbox API credentials

In the developer dashboard, go to Apps & Credentials and make sure you’re on the Sandbox tab (not Live). Click 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. Spree registers the sandbox webhook when you save.

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 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.

5. View sandbox transactions from the merchant side

To see transactions as the merchant, log in to 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. 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 refuses to register, or silently fails to deliver to, localhost or VPN-only addresses.

Features

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 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 live