Skip to content
Gaurav TiwariDocs

Set Up PayPal Payments

Version 1.0.0-beta.1 Updated November 8, 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 setups often treat recurring billing as a separate product with its own plans to build inside PayPal.

The PayPal module talks to PayPal’s REST APIs directly. It adds PayPal Smart Buttons and Pay Later to the EDD checkout, refunds from the EDD order screen 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. Fill in the settings under Stackless → Settings → PayPal and save.
  3. Go to Downloads → Settings → Payments and switch on PayPal (Stackless) under Active Gateways. Save.

PayPal (Stackless) is its own gateway, separate from the PayPal and PayPal Standard gateways that come with EDD.

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. Uses the PayPal sandbox, so no real money moves. This switch is separate from EDD’s Enable Test Mode.
  • Live credentials: Client ID, Secret and Webhook ID.
  • Sandbox credentials: Sandbox client ID, Sandbox secret and Sandbox webhook ID.

When you save with PayPal switched on in EDD, 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_EDD_PAYPAL_CLIENT_ID
STACKLESS_EDD_PAYPAL_CLIENT_SECRET
STACKLESS_EDD_PAYPAL_WEBHOOK_ID
STACKLESS_EDD_PAYPAL_SANDBOX_CLIENT_ID
STACKLESS_EDD_PAYPAL_SANDBOX_CLIENT_SECRET
STACKLESS_EDD_PAYPAL_SANDBOX_WEBHOOK_ID
The PayPal settings screen in Stackless for EDD with live and sandbox credentials, the webhook URL and events, payment options and button styles.

Connect the Webhook

Add https://yoursite.com/wp-json/stackless-edd/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 EDD.

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.

Checkout Settings

  • Title: shown to buyers at checkout. Default “PayPal”.
  • Description: default “Pay with your PayPal account, Pay Later, or a card through PayPal.”
  • Payment action: Capture immediately (default), or Authorize only (capture when the order status changes to Completed). Subscription orders are always captured immediately.
  • Brand name: shown on PayPal. Defaults to your site name.
  • Invoice prefix: default EDD-. PayPal rejects repeated invoice numbers, so give each store on the same PayPal account its own prefix.

An authorized order is captured when you change its status to Completed. Moving it to Revoked, Failed or Abandoned voids the authorization.

Button Settings

  • Layout: Vertical (default) or Horizontal.
  • Color: Gold (default), Blue, Silver, White or Black.
  • Shape: Rectangle (default), Pill or Sharp.
  • Label: PayPal (default), 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 EDD checkout and in the Payment methods tab of the customer account page. They don’t show on download pages. Without JavaScript, the buyer completes the purchase and is sent to PayPal to pay.

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 turned on for 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 new PayPal setup. On a store whose PayPal settings were saved before, 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. The buyer fills them in and clicks EDD’s Purchase button. PayPal hosts the fields, so card numbers never reach your site. PayPal’s own card button under the Smart Buttons is hidden while the card fields show, so buyers never see two card forms.

When PayPal doesn’t offer card fields to your account, the currency or the buyer, the fields stay hidden and the Smart Buttons get PayPal’s card button back, so buyers can still pay by card.

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’s off by default and needs:

  • Card fields turned on. For guests, Fastlane takes the place of the card fields.
  • A store whose country in EDD’s settings is 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. If Fastlane 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 EDD checkout, on devices and browsers that can pay with them.

Apple Pay also needs your domain added under Apple Pay in your PayPal app, for each environment you use. PayPal checks the domain association file, and Stackless serves it at https://yoursite.com/.well-known/apple-developer-merchantid-domain-association while PayPal and Apple Pay are on, using the sandbox or live file to match your Sandbox setting. The Apple Pay setting shows your exact URL.

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

Saved PayPal Accounts and Cards

When the cart contains a subscription, checkout saves the buyer’s PayPal account or card at PayPal and says so: future subscription payments are taken automatically, and the buyer can remove it any time from their account page.

A buyer who pays for a subscription with the card fields or Fastlane has the card saved at PayPal. It renews the same way and shows with its brand, last four digits and expiry date. A checkout with nothing due today, such as a free trial, always saves a PayPal account, because the card fields only show when there’s something to pay.

Signed-in customers also get a Payment methods tab on the customer account page. Its Saved with PayPal list shows their saved PayPal accounts and cards. They can save a PayPal account without paying anything and remove any saved method. Cards can’t be added there. Subscriptions that used a removed account ask for another payment method at renewal. If they remove the account inside PayPal, the webhook removes it in EDD too.

Saved cards report their expiry date to the Subscriptions module, so the Card expiring email in Stackless → Emails covers PayPal cards.

Subscription Renewals

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

A renewal fails straight away when the saved account belongs to the other environment (sandbox vs live), the currency isn’t one PayPal accepts or PayPal needs the customer to approve the payment. 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, the other environment or a currency PayPal doesn’t takeHardWith Declined for good on in Stackless → Settings → Subscriptions (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.

When a hard decline stops retries, the subscription note names the issuer’s code, such as 9520 for a lost or stolen card.

Post-purchase offers charge the PayPal account or card saved for the customer in one click. Only signed-in customers are charged this way, and never on a copy of the live store. If PayPal needs the buyer to approve the charge, they’re sent to PayPal first.

Refunds and Reversals

Refund from the EDD order screen, in full or in part. The refund form gets a Refund transaction in PayPal box, ticked by default. Untick it to record the refund in EDD only.

An order that was only authorized can’t be refunded. Revoke it to void the authorization instead. 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.
  • Card fields, Fastlane, Apple Pay and Google Pay run on the EDD checkout only. The account page saves PayPal accounts, not cards.
  • Fastlane works for stores based in the US charging US dollars, for guest buyers.
  • 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.
  • If PayPal reports a capture that doesn’t match the order total, an unpaid order goes on hold with a note to check the payment in PayPal before you deliver it.
  • Turn on Debug log to write API activity to Downloads → Tools → Debug Log, tagged stackless-edd-paypal_gateway, while EDD debug mode is on. Errors are always logged. Secrets never are.
  • PayPal can’t be duplicated with Payment Gateway Tools. Saved accounts belong to one PayPal app.
Share

Was this helpful?

Still stuck? Open a support ticket