Skip to content
Gaurav TiwariDocs

Set Up PayPal Payments

Updated November 7, 2026

Plenty of buyers won’t type a card number into a store they’ve just found, but they’ll click a PayPal button. The catch for subscription stores is that PayPal checkout plugins often treat recurring billing as a separate product with its own plans to set up in PayPal.

The PayPal module talks to PayPal’s REST APIs directly. It adds PayPal Smart Buttons and Pay Later to the block and classic checkout, refunds from WooCommerce, and saves the buyer’s PayPal account so Stackless can charge subscription renewals itself. It can also take cards on the checkout page through PayPal, with 3-D Secure, Fastlane for guests, and Apple Pay and Google Pay buttons.

Turn On the Gateway

  1. Switch on the PayPal module under Stackless → Dashboard.
  2. Go to WooCommerce → Settings → Payments → PayPal (Stackless).
  3. Tick Enable (Accept payments with PayPal) and fill in the settings below.

Stackless → Settings → PayPal only shows a link to that screen and your webhook URL.

Add Your Credentials

Create an app at developer.paypal.com → Apps & Credentials. For subscriptions, the app needs the Vault feature turned on. Card fields, Fastlane, Apple Pay and Google Pay also need Advanced Credit and Debit Card Payments turned on for the app.

  • Sandbox: on by default. No real money moves.
  • Live credentials: Client ID, Secret and Webhook ID.
  • Sandbox credentials: Sandbox client ID, Sandbox secret and Sandbox webhook ID.

When you save with PayPal enabled, Stackless requests a token from PayPal to test the credentials for the selected environment. You’ll see an error if the client ID or secret is empty or rejected, and a reminder if the webhook ID is missing.

You can also keep credentials out of the database by defining constants in wp-config.php. A defined constant wins over the saved setting:

STACKLESS_PAYPAL_CLIENT_ID
STACKLESS_PAYPAL_CLIENT_SECRET
STACKLESS_PAYPAL_WEBHOOK_ID
STACKLESS_PAYPAL_SANDBOX_CLIENT_ID
STACKLESS_PAYPAL_SANDBOX_CLIENT_SECRET
STACKLESS_PAYPAL_SANDBOX_WEBHOOK_ID

Connect the Webhook

Add https://yoursite.com/wp-json/stackless/v1/paypal/webhook as a webhook in each PayPal app, live and sandbox. The Webhook section of the settings shows your exact URL. Subscribe to:

PAYMENT.CAPTURE.COMPLETED
PAYMENT.CAPTURE.PENDING
PAYMENT.CAPTURE.DENIED
PAYMENT.CAPTURE.DECLINED
PAYMENT.CAPTURE.REFUNDED
PAYMENT.CAPTURE.REVERSED
VAULT.PAYMENT-TOKEN.CREATED
VAULT.PAYMENT-TOKEN.DELETED

Then paste the webhook ID PayPal shows into Webhook ID or Sandbox webhook ID. Every event is checked with PayPal’s signature verification before anything runs, and each event is applied only once. Without the webhook, refunds made in PayPal, delayed payments and saved-account changes won’t reach WooCommerce.

Billing Health flags missing credentials or a missing webhook ID, sandbox mode on the live store and Fastlane turned on without the card fields. It also lists PayPal webhook events that failed or never finished in the last 7 days.

Payment Settings

  • Payment action: Capture immediately, or Authorize only and capture when the order moves to Processing or Completed. Subscription orders are always captured immediately. Cancelling an order releases its authorization.
  • Brand name: shown on PayPal. Defaults to your site name.
  • Invoice prefix: default WC-. PayPal rejects repeated invoice numbers, so give each store on the same PayPal account its own prefix.

Button Settings

  • Layout: Vertical or Horizontal.
  • Color: Gold, Blue, Silver, White or Black.
  • Shape: Rectangle, Pill or Sharp.
  • Label: PayPal, PayPal Checkout, Buy Now or Pay with PayPal.
  • Pay Later messaging: shows Pay Later offers under the buttons where PayPal supports them, on by default.

The buttons show on the checkout, the order-pay page and My Account → Add payment method. They don’t show on product or cart pages.

Card Fields and 3-D Secure

The Cards and wallets section adds ways to pay without a PayPal account. Each one needs Advanced Credit and Debit Card Payments on your PayPal app (Apps & Credentials → your app → Features), and shows only where PayPal says your account and the buyer are eligible.

  • Card fields: lets buyers pay by card on the checkout page. On for a fresh PayPal setup. On a store whose PayPal settings were saved earlier it starts off, so checkout doesn’t change until you tick it.
  • 3-D Secure: “When the bank or regulation requires it” (default) or “On every card payment”.

With card fields on, the PayPal payment method shows the buttons first, then “Or pay with a card” with Name on card, Card number, Expiry date and Security code. PayPal hosts the fields, so card numbers never reach your site. They work on the block and classic checkout and on the order-pay page. PayPal’s own card button under the Smart Buttons is hidden while card fields are on, so buyers never see two card forms.

PayPal runs 3-D Secure in the card fields when it applies. If the bank’s check fails, the payment isn’t captured: the buyer is asked to use another card, and the order gets a note. If the check couldn’t finish, they’re asked to try again.

Fastlane

Fastlane by PayPal lets guests pay with a card saved in their Fastlane profile. Tick Fastlane (Offer Fastlane by PayPal to guest buyers). It needs:

  • Card fields turned on. For guests, Fastlane takes the place of the card fields.
  • A store based in the United States, charging US dollars.
  • A guest buyer. Signed-in customers see the regular card fields.

When a guest enters their email at checkout, PayPal looks it up. If they have a Fastlane profile, PayPal asks them to confirm it’s them and shows their saved card; otherwise they type a card into the same box. Fastlane shows on the checkout page only, not on the order-pay page. If it can’t load, the regular card fields show instead.

Apple Pay and Google Pay

Tick Apple Pay (Show Apple Pay through PayPal) or Google Pay (Show Google Pay through PayPal) to add their buttons to the PayPal payment method. Both are off by default and take one-time payments only: carts that start a subscription hide them. They show on the checkout and the order-pay page, and only on devices and browsers that can pay with them.

Apple Pay also needs your domain registered with PayPal, in the sandbox app and the live app:

  1. In the PayPal Developer Dashboard, open Apps & Credentials, select your app and go to Features → Accept payments → Advanced Credit and Debit Card Payments.
  2. Turn on Apple Pay if it’s off, click Manage in the Apple Pay section and add your domain.
  3. PayPal checks the domain association file. Stackless serves it at https://yoursite.com/.well-known/apple-developer-merchantid-domain-association while PayPal and Apple Pay are enabled, using the sandbox or live file to match your Sandbox setting.

Open that URL in a browser before you register: it should download a file. Some hosts and security plugins block paths that start with /.well-known/. If yours does, ask your host to let this one through to WordPress.

Saved PayPal Accounts and Cards

When the cart contains a subscription, checkout saves the buyer’s PayPal account and tells them so: future subscription payments are taken automatically, and they can remove the account in PayPal any time.

A buyer who pays for a subscription with the card fields or Fastlane has the card saved at PayPal instead. It renews the same way and shows in My Account → Payment methods with its brand and last four digits. A checkout with nothing due today, such as a free trial, always saves a PayPal account, because the card fields need a payment to save a card.

Customers can also save a PayPal account from My Account → Payment methods → Add payment method, and pick it for a subscription from the subscription’s page. If they remove it in PayPal, the webhook removes the saved method in WooCommerce too. Cards can’t be added from that page.

Subscription Renewals

PayPal renews subscriptions automatically by charging the saved PayPal account or card. Like Stripe, it supports several subscriptions in one order, free-trial signups with nothing due today, payment method changes and next-payment date changes.

A renewal fails straight away when the saved account belongs to the other environment (sandbox vs live) or the currency isn’t one PayPal accepts. Failed renewals follow your retry schedule from Renewals, Failed Payments and Retries.

When a renewal fails, Stackless records why, from the card issuer’s response code or PayPal’s error, and your retry schedule adapts to it:

What PayPal reportedRecorded asWhat happens next
Closed, expired, lost or stolen card, suspected fraud, a saved method PayPal no longer accepts, no saved method, or the other environmentHardWith Declined for good on (the default), no more automatic retries. The customer is asked to pay or change the payment method.
Insufficient funds or over a limitFundsThe next retry waits at least 3 days.
The bank wants 3-D Secure, or PayPal needs the buyer to approve the paymentAuthenticationNo automatic retries. The customer pays from the link.
PayPal or the card network couldn’t complete the requestNetworkRetried on your schedule.
Any other declineSoftRetried on your schedule.

Post-purchase offers charge the PayPal account or card saved for the customer in one click. If PayPal needs the buyer to approve the charge, they’re sent to PayPal first.

Refunds and Reversals

Refund from the WooCommerce order screen, in full or in part. Refunds made inside PayPal are recorded on the order through the webhook. A reversal from a chargeback or buyer dispute puts the order on hold with a note to review it in PayPal.

Moving From WooCommerce PayPal Payments

When you move subscriptions from WooCommerce Subscriptions, the ones that renewed through WooCommerce PayPal Payments keep renewing through PayPal here. Stackless looks up each saved PayPal account, Venmo account or card at PayPal with your app’s credentials for the matching mode, and saves it for this gateway.

  • Add credentials from the same PayPal business account before you import.
  • Saved Apple Pay methods can’t renew here. Those subscriptions, and any whose saved method PayPal doesn’t return, switch to manual renewal and renewals are emailed as pay links.
  • Subscriptions billed through PayPal’s own subscription plans have no saved method to move, so they renew manually too.

Limits

  • PayPal is hidden at checkout for currencies it doesn’t take. The supported list is AUD, BRL, CAD, CNY, CZK, DKK, EUR, HKD, HUF, ILS, JPY, MYR, MXN, TWD, NZD, NOK, PHP, PLN, GBP, SGD, SEK, CHF, THB and USD.
  • Saved accounts for automatic renewals need the Vault feature on your PayPal app.
  • Fastlane works for stores based in the US charging US dollars, for guest buyers, on the checkout page.
  • Apple Pay and Google Pay take one-time payments only, and Apple Pay needs your domain registered with PayPal.
  • A subscription checkout with nothing due today saves a PayPal account, not a card.
  • Turn on Debug log to write API activity to WooCommerce → Status → Logs (stackless-paypal_gateway). Secrets are never logged.
Share

Was this helpful?

Still stuck? Open a support ticket