Set Up PayPal Payments

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.

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.

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

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.

Saved PayPal Accounts

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.

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.

Subscription Renewals

PayPal renews subscriptions automatically by charging the saved account. 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.

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.

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.
• Turn on Debug log to write API activity to WooCommerce → Status → Logs (stackless-paypal_gateway). Secrets are never logged.