PayPal Checkout
ProEvents Manager Pro - PayPalRequires Events Manager Pro. Compare plans
PayPal Checkout shows PayPal's buttons in your booking form. The customer clicks one, approves the payment in a PayPal window, and the booking is approved when PayPal confirms the money was captured.
For card fields on the form itself, see PayPal Advanced. The PayPal page compares the two.
- Events Manager Pro 3.2.7 or later and the Events Manager Pro - PayPal plugin, both activated. This page describes PayPal add-on 1.5.0.
- A PayPal Business account and access to the PayPal Developer Dashboard.
- Your site served over HTTPS and reachable from the internet. PayPal has to be able to call your site, so the webhook can't be created on a local development site.
Set up PayPal Checkout
-
In the PayPal Developer Dashboard, create a REST API app in Sandbox mode for testing. PayPal gives the app a Client ID and a Secret. Later you will create a second app in Live mode for real payments.
-
In WordPress, go to Events then Payment Gateways and click Paypal Checkout. A new gateway starts in test mode.
-
Open the [Test] API Keys/Notifications tab. Paste the sandbox app's values into Client ID and Client Secret and click Save Changes.
Client ID and Client Secret for the sandbox app. Payment Notifications below reports whether the webhook is in place.
-
Read the notice at the top of the page. Saving contacts PayPal, checks the credentials and creates the webhook. You should see Credentials are sucessfully saved, and webhook has beon created for you. You're all set! (the spelling is the plugin's). Under Payment Notifications a green line confirms that a valid webhook was set up.
-
Go back to Events then Payment Gateways and click Activate under Paypal Checkout.
-
Book a priced event and pay with a PayPal sandbox buyer account. The booking should be Approved in Events then Bookings with a Completed transaction.
-
To go live, paste the live app's Client ID and Client Secret into the [Live] API Keys/Notifications tab, save, check for the same notice, then click Enable Live Mode in the banner above the tabs.
The credentials are shared with PayPal Advanced. If you use both gateways, enter them once.
The webhook
The webhook is how PayPal tells your site about payments that complete later, and about refunds and disputes. You don't create it. Every time you save the gateway's settings, the add-on looks for its webhook on your PayPal app, creates it if it is missing, and updates its address and events if they have changed. Don't delete it in PayPal.
It subscribes to these events:
| Event | What Events Manager does with it |
|---|---|
PAYMENT.CAPTURE.COMPLETED | Approves a booking whose payment PayPal had been holding as pending, or records a payment your site missed. |
PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.DECLINED | Records the payment as Denied. A booking still waiting for payment is deleted, and a booking that was already Pending is cancelled. |
PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, PAYMENT.SALE.REFUNDED, PAYMENT.SALE.REVERSED | Records a refund. |
CUSTOMER.DISPUTE.CREATED | Records a dispute. |
Open the PayPal gateway settings and click Save Changes once. Older versions subscribed to fewer events, and saving adds the new ones to your existing webhook. A notice in wp-admin asks for this until it is done. Do it for live and test credentials.
If the webhook can't be created, the page shows an error beginning Could not create webhook, followed by the address and the list of events. Fix the credentials and save again. Only if that keeps failing, create a webhook by hand on the app in PayPal with exactly that address and those events.
Settings
General Options
| Setting | What it does |
|---|---|
| Gateway Title | The name in the payment method menu. Default PayPal Checkout. |
| Booking Form Information | Text shown under the menu when this gateway is chosen. |
| QuickPay Payment Button | Button text when Quick Pay Buttons are on. Default Pay with Paypal. |
| Success Message | Shown once the payment is captured. |
| Return URL | A page to send the customer to after paying. Leave it empty to show the success message in place, with no redirect. |
| Thank You Message | Shown on the Events Manager thank you page, if you use it as the return page. |
| Unpaid Bookings Expiry, Expired Booking Action | How long an unpaid booking waits and what happens to it then. See Unpaid bookings. |
| Manually approve completed transactions? | Leaves paid bookings at Pending for you to approve. Bookings must also need approval in your booking settings. |
| Payment Cancelled Message | Shown when the customer closes the PayPal window without paying. |
PayPal Options
| Setting | What it does |
|---|---|
| Include Taxes In Itemized Prices | Yes sends PayPal ticket prices with tax already included. No sends prices without tax and the tax total as a separate amount. The help text under the field describes these the other way round. What is written here is what the add-on does. |
| Disabled Funding Sources | Tick the payment types you don't want offered: cards, PayPal Credit, Pay Later, Venmo and a list of local methods such as iDEAL, Bancontact and BLIK. Everything unticked is allowed, but PayPal still decides which of them each customer is eligible for, based on your account, your country and theirs. |
The [Test] API Keys/Notifications tab also has the Limited Test Mode settings. PayPal's script can only be loaded once per page, so limiting test mode to one event while other booking forms on the same page are live may not behave as expected.
What the customer sees
The PayPal buttons replace the booking form's submit button for this payment method. Clicking one submits the form and opens PayPal's window. While it is open the form shows Booking in progress, Please proceed with payment in the PayPal window. with a Cancel link. When the customer approves the payment, the window closes, your site captures the payment and the success message appears.
PayPal receives one line per ticket type with its quantity and price, any surcharges and discounts, and tax according to the setting above.
Pending payments
Some payments don't clear at once. An eCheck is the usual example, and PayPal can also hold a payment for review. PayPal reports these as pending.
A pending payment does not approve the booking. Events Manager records a Pending transaction and sets the booking to Pending, which also stops it expiring as unpaid. When PayPal settles the payment it sends PAYMENT.CAPTURE.COMPLETED and the booking is approved, or PAYMENT.CAPTURE.DENIED and the booking is cancelled. If you approved, rejected or cancelled the booking yourself in the meantime, the payment is recorded and your decision is left alone.
Unpaid, abandoned and declined payments
- The customer closes the PayPal window or clicks Cancel. Your site asks PayPal whether the order was paid. If not, the booking is deleted and the Payment Cancelled Message is shown above the form, ready for another try.
- The payment is declined. The customer sees Your payment was declined. Please try another card or payment method. and the booking is deleted. In Multiple Bookings Mode their cart is given back.
- The result is unclear. The customer sees a message asking them not to pay again, and the booking is kept for the webhook or the expiry check to settle.
- The customer leaves. When the Unpaid Bookings Expiry runs out, Events Manager asks PayPal about the order. A paid order approves the booking. An unpaid one gets the Expired Booking Action. If PayPal can't be reached, the booking is kept and cancelled a day after its expiry.
PayPal Checkout adds no button to My Bookings. Switch on the payment page to let customers pay an unpaid booking later.
Refunds
Refund a payment from your PayPal account. There is no refund button in WordPress. PayPal notifies your site and a Refunded transaction with a negative amount is recorded.
- A full refund, or partial refunds that add up to everything paid, cancels the booking.
- Any other partial refund sets the booking to Pending, without a status email.
- A booking paying a deposit and balance is only cancelled once nothing is left paid.
Disputes
When a customer opens a dispute, PayPal sends CUSTOMER.DISPUTE.CREATED. Events Manager records a Disputed transaction whose note gives the disputed amount and PayPal's reason. A dispute for the full booking price cancels the booking, and a smaller one sets it to Pending. If PayPal later reverses the payment, that arrives as a refund.
Your site is not told how a dispute ends. If it is resolved in your favor, approve the booking again yourself.
Troubleshooting
PayPal buttons do not appear
Check that the gateway is Active, that the page is loaded over https://, and that credentials are saved for the mode the gateway is in. After saving with a set missing, the page says You have not entered that mode's credentials.
A button I expect is missing
PayPal decides which funding sources a customer is eligible for. Check that the source isn't ticked under Disabled Funding Sources, then check its availability for your account and country with PayPal.
"Could not create webhook" when saving
The credentials were rejected or PayPal could not be reached. Check that the Client ID and Secret are from the same app and from the right environment: sandbox values on the Test tab, live values on the Live tab.
Payment Notifications says there is no valid webhook
The webhook was deleted in PayPal, or the site address changed. Click Save Changes to create it again.
Refunds or completed eChecks are not updating bookings
Save the gateway settings once so the webhook has every event listed above, then check Payment Notifications for the green confirmation.