The PayPal buttons do not show
Check in this order:
- Is the active environment connected? The General tab shows Connected or Not connected for Sandbox and Live. Payment methods belong to one environment; switching to Live with only a sandbox account connected shows nothing.
- Is the method switched on for this environment? Sandbox and Live keep separate payment-method switches.
- Is the page ticked? Show buttons on on the PayPal tab decides where the buttons appear. The product page is not ticked by default.
- Is it hidden on this product? A product's Product data → General panel can disable express buttons, Pay Later, Venmo, Apple Pay or Google Pay for that product.
- Is Admin only mode on? Then only administrators and shop managers see the PayPal methods.
- Is "Use Place Order button" on? Then there are no PayPal buttons on the checkout — the shopper presses Place order and approves at PayPal.
- Does the browser console show an error? A script optimisation plugin that delays, combines or defers scripts can stop PayPal's SDK from loading. Exclude the PayPal scripts and
www.paypal.comfrom it.
"Automatic updates: Not active"
PayPal could not register the webhook. On a public HTTPS site, disconnect and reconnect the account; the subscription is registered on the next admin page load. A firewall or security plugin must let PayPal POST to /wp-json/gatemi-paypal/v1/webhook — the endpoint is public by design and trusted only after the signature check.
"Local site" is expected on localhost, a .test domain or a private network address: PayPal cannot reach those. Test payments still work.
Do I need webhooks?
Payments are captured in the same request, so orders are right without them. Without webhooks you miss refunds and disputes made in PayPal, pending captures that clear later, and shoppers who approved and closed the tab before returning.
Card payments are not offered
Advanced Card Processing must be enabled on your PayPal account. The Credit / Debit Card row on the General tab shows its status and a setup link. Press Refresh status after PayPal approves it.
Apple Pay does not show
The Apple Pay tab's checklist must be all green: Apple Pay enabled in your PayPal account, HTTPS, and the domain verification file in place. The plugin serves Apple's file at /.well-known/apple-developer-merchantid-domain-association; your domain must also be registered for Apple Pay in your PayPal account. Test in Safari on a device with a card in Wallet.
Pay Later messages do not show
Messaging needs two things: Pay Later messaging switched on in the General tab, and at least one page chosen under Display on on the Pay Later tab — no page is chosen by default, so switching messaging on shows nothing until you choose the pages. PayPal also decides per country and amount whether an offer exists.
A card payment was declined after 3-D Secure
With Liability shift handling on Smart (the default), a card that failed the bank's verification is blocked and the shopper can try again. On Reject, cards without full verification are declined too — switch to Smart if genuine customers are turned away. Turn on 3D Secure logging and check the gmpfw-3ds log.
An order is "On hold — PayPal payment is pending"
PayPal accepted the payment but is holding it, for example for review or an unconfirmed address. The PAYMENT.CAPTURE.COMPLETED webhook moves the order on when PayPal releases it. With Instant payments on (the default), slow eCheck payments are refused up front.
Sandbox orders cannot be captured after I went live
Capture, re-authorize, void and refund all use the connection that is active now, and are refused for an order paid in the other environment. Capture, re-authorize and void leave an order note; a refund is refused with the message This order was paid in sandbox mode, but the plugin is currently connected to live. Switch the plugin environment to refund this payment. Switch Environment back to manage the order. (Orders recorded before the plugin stored the environment on the order are not checked.)
Does it work with the Cart and Checkout blocks and HPOS?
Yes. It declares compatibility with High-Performance Order Storage and with the blocks. The block checkout and the classic checkout use the same SDK and the same payment flow.
Does it work with page caching?
Never cache the cart, checkout or My Account pages (cache plugins exclude them by default). Product pages with buttons can be cached: checkout nonces are refreshed through wc-ajax=gmpfw_refresh_nonces, and the amount is always built on the server from the cart.
Two stores share one PayPal account
Give each a different Invoice prefix on the Advanced tab. PayPal refuses a second payment with an invoice number it has already seen.
I am moving from another PayPal plugin
Connect the same PayPal account, then deactivate the old plugin — nothing is adopted while it is active. Past orders can be refunded and saved Vault v3 methods keep renewing. PayPal Standard recurring profiles (I-…) are refused on purpose. See Moving from another PayPal plugin.
What happens when I uninstall?
By default, nothing is deleted — settings and saved methods stay for a future reinstall. With Remove data on uninstall ticked (Advanced tab), deleting the plugin removes its settings, encrypted credentials, encryption key, gateway options, webhook records and cached tokens, every _gmpfw_ meta value on orders and products, and the saved payment tokens of its gateways. The orders themselves stay. The webhook subscription and the app connection at PayPal are not removed; disconnect the account first if you want that.
What does the plugin send outside my site?
Payments go to PayPal's REST API (api-m.paypal.com, sandbox api-m.sandbox.paypal.com), and PayPal's SDK loads on checkout, cart and product pages. Google Pay's script loads only when Google Pay is on. reCAPTCHA calls Google only when you turn it on. The Connect button calls a partner onboarding service once, to create the sign-up link. Requests carry a PayPal partner attribution id; the plugin's author is a PayPal partner.
