The plugin is PPCP only: PayPal's REST Orders v2, Payments v2 and Vault v3 APIs and the Web SDK v6. There is no legacy Express Checkout (NVP), PayPal Pro, Payflow, Braintree or IPN code in it. The classic checkout and the Cart and Checkout blocks load the same SDK through one loader, so both behave the same.
The gateways
| Gateway id | Shown as |
|---|---|
gmpfw_paypal |
PayPal (with Pay Later and Venmo inside its buttons) |
gmpfw_card |
Credit / Debit Card (Advanced Card Processing) |
gmpfw_applepay |
Apple Pay |
gmpfw_googlepay |
Google Pay |
gmpfw_fastlane |
Fastlane |
Local methods such as iDEAL, Bancontact, BLIK, eps, Przelewy24, MyBank, Trustly and Multibanco appear as funding options inside the PayPal buttons, when PayPal offers them to that shopper. Hide any of them with Hide payment options on the PayPal tab. Separate redirect gateways for them exist in the code but are off unless a developer switches them on (see the developer reference).
A PayPal payment, step by step
- The shopper presses the PayPal button. The page asks your store (
wc-ajax=gmpfw_create_order) to create a PayPal order from the cart — amounts, line items (when Send item details is on), shipping and your Brand name. The PayPal order id is kept in the shopper's WooCommerce session. - The shopper approves in PayPal's window.
- The checkout is submitted. The gateway checks that the PayPal order id posted is the one in the session — a forged id is refused.
- The plugin writes your WooCommerce order id (
custom_id) and invoice number (Invoice prefix + order number) onto the PayPal order, then captures it. That correlation is how webhooks and refunds find the order later. - PayPal's answer decides the order:
| Capture status | Order |
|---|---|
COMPLETED |
Paid (WooCommerce's normal status, usually Processing; Completed with Auto-complete orders). Note: PayPal payment captured via … (capture …). |
PENDING |
On hold — PayPal payment is pending (reason). The PAYMENT.CAPTURE.COMPLETED webhook completes it later |
| declined | The shopper sees the error and can try again |
The transaction id, PayPal's fee and net, the seller-protection status and the environment (sandbox or live) are stored on the order.
With "Use Place Order button"
No PayPal buttons show at checkout. The shopper presses Place order, the store creates the PayPal order on the server and sends them to PayPal to approve. When they come back (wc-ajax=gmpfw_paypal_return) the payment is captured or authorized as above.
Express buttons
On product pages, the cart, the mini-cart and the top of the checkout, the PayPal, Apple Pay and Google Pay buttons start a payment before the shopper has filled in the checkout. PayPal returns the shipping address; shipping is quoted on your server as the shopper changes address in the PayPal window. With Skip order review on (the default) the order is placed as soon as they approve; with it off they come back to your checkout to review first.
Saved checkout from an approved order
If a shopper approves at PayPal and then closes the tab before your store captures, the CHECKOUT.ORDER.APPROVED webhook is the backstop that lets the store complete it.
Authorize, then capture
With Payment action set to Authorize (store-wide, or per method on the Credit Card, Apple Pay and Google Pay tabs), the money is only reserved:
- The order goes to Authorized order status (On hold by default).
- Moving it to a status in Capture on status change (Processing or Completed by default) captures it automatically.
- The order's Order actions menu offers Capture PayPal authorization, Re-authorize PayPal authorization and Void PayPal authorization. A partial capture can be taken from the order screen.
- With Void on cancel (on by default), cancelling the order releases the reservation.
PayPal authorizations expire; the plugin records when, and re-authorizing gets a fresh one.
Capture, re-authorize and void are refused — with an order note — when the order was paid in the other environment from the one the plugin is connected to now.
Cards and 3-D Secure
Card fields are PayPal's hosted fields, so card numbers never reach your server. 3-D Secure runs When required by default (or Always, or Never). After the bank's check, Liability shift handling decides: Smart blocks only cards that failed verification and lets the shopper try again; Reject declines anything without full verification; Review and Accept let everything through, Review noting the result on the order. The result is stored on the order (_gmpfw_3ds_*).
Fastlane
For US merchants in USD with Advanced Card Processing. A guest typing their email is recognised as a Fastlane shopper, confirms a one-time code and pays with their saved card — or, with the Express checkout button flow, chooses Fastlane from the express buttons. New shoppers can join at checkout.
Refunds
WooCommerce's Refund button refunds through PayPal, in full or in part. A refund made in the PayPal dashboard reaches the order through the PAYMENT.CAPTURE.REFUNDED webhook and is recorded as a WooCommerce refund ("Refunded in PayPal."), without calling PayPal again — so it is not refunded twice. A refund the store itself sent is recognised by its id and skipped. PAYMENT.CAPTURE.REVERSED is recorded the same way.
A refund for an order paid in the other environment (a sandbox order while the plugin is connected to live, or the reverse) is refused before anything is sent to PayPal, with a message telling you to switch the environment — the capture does not exist in the connection that is active now.
Refund on cancel (off by default) refunds automatically when an order is cancelled.
Disputes
When a shopper opens a dispute (CUSTOMER.DISPUTE.CREATED), the order moves to Order status on dispute (On hold by default), its previous status is remembered, and a note gives the dispute id and reason. When it is resolved in your favour the previous status is restored; when it is resolved in the buyer's favour a note says a refund may have been issued.
Webhooks
PayPal posts events to /wp-json/gatemi-paypal/v1/webhook. The plugin registers this subscription itself after a connection and reconciles it at most once a day per environment, from the daily cron event gmpfw_webhook_daily_check and when you open the settings screen. For each event:
- The signature is verified — offline, against PayPal's cached signing certificate, falling back to PayPal's verification API.
- The event id is claimed so a redelivered event is applied once.
- The order is found by the
custom_idwritten on the PayPal order, with a transaction-id lookup as fallback, and checked to belong to this store. - The event is applied:
| Event | What happens |
|---|---|
PAYMENT.CAPTURE.COMPLETED |
A pending capture is marked paid. A completed capture with a different id on an already-paid order is flagged in a note as a possible double charge |
PAYMENT.CAPTURE.PENDING |
On hold — pending review |
PAYMENT.CAPTURE.DENIED |
Failed |
PAYMENT.CAPTURE.REFUNDED, .REVERSED |
Recorded as a WooCommerce refund |
PAYMENT.AUTHORIZATION.VOIDED |
Cancelled, unless money was already captured |
CHECKOUT.ORDER.APPROVED |
Completes an approved order the shopper never returned from |
CUSTOMER.DISPUTE.CREATED, .RESOLVED |
See Disputes |
VAULT.PAYMENT-TOKEN.CREATED, .DELETED |
Adds or removes a saved payment method |
On a local or private-network site PayPal cannot deliver, so nothing is registered. Payments still work; only these follow-ups are missed.
Saved payment methods and subscriptions
With Save payment methods on (and PayPal's vault approval on your account), signed-in shoppers can save PayPal, Venmo or a card at checkout or in My Account → Payment methods. The method is stored by PayPal (Vault v3); WooCommerce keeps only a token. WooCommerce Subscriptions renewals are charged against the saved token with nobody present, and zero-total free trials save the method without a charge. WooCommerce Pre-Orders are charged the same way.
Pay Later messaging
When Pay Later messaging is on and you have picked pages on the Pay Later tab, PayPal's own message (for example an instalment offer) shows under prices on those pages. The terms in it come from PayPal.
Moving from another PayPal plugin
Orders and subscriptions are bound to the gateway id of the plugin that took them. While that plugin is deactivated, this plugin answers to the ids of WooCommerce PayPal Payments (ppcp-gateway, ppcp-credit-card-gateway), WooCommerce PayPal Checkout (ppec_paypal), AngellEYE's PayPal for WooCommerce and others. Ids are translated when an order is read; no order is rewritten. This means:
- Old orders can be refunded through their recorded transaction id.
- Saved methods that already exist as Vault v3 tokens on your PayPal account keep renewing subscriptions.
- Legacy
B-…billing agreements are used only if Reference Transactions are still enabled on your PayPal account. - PayPal-managed recurring profiles (
I-…ids, from PayPal Standard) are refused with an order note, because PayPal keeps billing those on its own schedule and charging them here too could bill the customer twice. Cancel the profile in PayPal and ask the customer to subscribe again.
Use the same PayPal account as before.
Security
Client secrets and the reCAPTCHA secret are encrypted at rest with a key the plugin creates on first use. Secrets, tokens and card numbers are removed from every log line.
