Next File Manager 6.1.0: share links, Trash, a phone app and a Health check Next Exams 6.3.0: exam parts, scaled scores, listening and speaking tests Next Restaurant 6.1.0: move your data in, run payroll, and connect other systems Next Inventory 6.2.0: a REST API and webhooks for your other systems Next DB 6.1: Auto-Updating Tables, Printing, Phone Layout and SEO Next Task 6.0.0: a task manager for Joomla
NextSoftware

PayPal

PayPal Checkout buttons on your booking page, with Pay Later, debit or credit cards and Venmo where PayPal offers them. PayPal payments can be refunded from the booking, and disputes are reported on it.


How the flow works

  1. The guest chooses PayPal at checkout, or pays a balance from their booking page. PayPal's buttons appear in the page.
  2. Your site creates a PayPal order for the amount due. The guest approves it in PayPal's window.
  3. Your server, never the browser, then captures the order: when the guest comes back, or, if they never do, when PayPal's CHECKOUT.ORDER.APPROVED webhook arrives. Capturing twice is harmless; PayPal takes the money once.
  4. PayPal's webhook also reports the capture, so the booking is confirmed even when the guest closes the window.

A capture PayPal marks as pending (an eCheck, or a currency your PayPal account must accept by hand) shows on the booking as authorised, and becomes paid when PayPal reports it completed.


What PayPal does not do here

  • No saved cards. A property set to collect its balance Automatic, from a saved card falls back to sending the guest their pay link when they paid with PayPal.
  • No damage deposit card holds. A pre-authorisation needs a saved card, which only Stripe provides.

Setting it up

1. Create an app at PayPal

In the PayPal Developer Dashboard, open Apps and Credentials and create an app, once under Sandbox and once under Live. Each app has a client ID and a secret.

2. Create the method

Open Configure > Payment methods, click Add method and pick PayPal. On the General tab set the Title, Description, Published, and keep Test mode on (test mode uses the sandbox).

On the Settings tab:

Field Value
Sandbox client ID, Sandbox secret From your sandbox app. Both must come from the same app
Sandbox webhook ID The ID PayPal gives the sandbox webhook you create in step 3
Live client ID, Live secret, Live webhook ID The same for your live app
Brand name The name the buyer sees on PayPal's pages (optional)
Offer Pay Later On by default. PayPal still decides whether a buyer sees it, by their country and the currency
Offer debit or credit card On by default. Lets buyers pay by card without a PayPal account
Offer Venmo On by default. Venmo is only for buyers in the US paying in USD

Save the method. Its Webhook tab now shows the Webhook address.

The method is not offered at checkout until its current mode has the client ID, the secret and the webhook ID.

3. Register the webhook at PayPal

In the PayPal Developer Dashboard, open your app, go to Webhooks and add a webhook:

  • Webhook URL: the address from the method's Webhook tab, for example https://your-site/index.php?option=com_nextselfcatering&task=payment.notify&format=raw&method=4. Copy it from the tab.
  • Event types:
Event Code
Checkout order approved CHECKOUT.ORDER.APPROVED
Payment capture completed PAYMENT.CAPTURE.COMPLETED
Payment capture denied PAYMENT.CAPTURE.DENIED
Payment capture declined PAYMENT.CAPTURE.DECLINED
Payment capture refunded PAYMENT.CAPTURE.REFUNDED
Payment capture reversed PAYMENT.CAPTURE.REVERSED
Customer dispute created CUSTOMER.DISPUTE.CREATED
Customer dispute updated CUSTOMER.DISPUTE.UPDATED
Customer dispute resolved CUSTOMER.DISPUTE.RESOLVED

PayPal then shows a Webhook ID. Copy it into Sandbox webhook ID (or Live webhook ID for the live app).

Every webhook is checked with PayPal's own signature verification for that webhook ID. Without a webhook ID, every delivery is refused.

4. Check the credentials

Click Test connection. It asks PayPal for an access token with the client ID and secret of the current mode, and says if the webhook ID is still missing.


Test it

  1. In the PayPal Developer Dashboard, under Sandbox accounts, use or create a personal (buyer) account.
  2. Book a property on your site, choose PayPal and log in with that sandbox buyer.
  3. Check the booking: the payment shows and the booking is confirmed.
  4. Book again, approve the payment in PayPal's window, then close the browser before returning. The booking should still be confirmed through the webhook.
  5. Refund part of a payment from the booking's payments card, and check it in the sandbox account.

Go live

  1. Enter the Live client ID, Live secret and Live webhook ID (create the webhook on the live app with the same address and events).
  2. Switch Test mode off and click Test connection.
  3. Take one small real payment and refund it.

Sandbox and live are kept apart: the sandbox credentials and webhook ID are used only in test mode.


Refunds

Refunds from a booking go to PayPal against the order's capture, in part or in full. The refund reason you type is sent to PayPal as the note to the buyer. A refund made in PayPal itself is recorded on the booking through PAYMENT.CAPTURE.REFUNDED, once.

If PayPal gives no answer to a refund, the booking shows Refund ... has no answer from the gateway: check PayPal and record what happened.


Disputes and reversals

A dispute opened by the buyer shows on the booking with the amount, the reason and the date to respond by, and staff get an email. Respond at the gateway opens PayPal's Resolution Center. When the dispute is resolved the booking shows whether you won or lost.

When PayPal takes money back itself (PAYMENT.CAPTURE.REVERSED, a chargeback or a bank reversal), it is recorded as a lost dispute.


Currencies

PayPal is offered for properties priced in AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB or USD. BRL, CNY and MYR work only for PayPal accounts in those countries. HUF and TWD are left out.


Requirements

  • A PayPal business account and a developer app.
  • HTTPS and a site PayPal can reach for the webhook.
  • PHP's cURL extension, and outgoing HTTPS to api-m.paypal.com (live) and api-m.sandbox.paypal.com (sandbox). The guest's browser loads PayPal's script from www.paypal.com.

Troubleshooting

Symptom Cause and fix
PayPal is not offered at checkout The method is unpublished, its app is off, the current mode lacks the client ID, secret or webhook ID, or the property's currency is not one PayPal takes
"PayPal refused the credentials." The client ID and secret are not from the same app, or not from the mode (sandbox or live) the Test mode switch selects
"PayPal could not be reached." Your server cannot make outgoing HTTPS requests
Guest approved, booking still held The webhook does not arrive, or its ID in the method is wrong. The webhook ID must be the one of the app for the current mode
PayPal shows the webhook failing with 400 The signature did not verify for the webhook ID in the method
PayPal shows 404 The method was deleted, or the address has the wrong method id
"This PayPal order has no capture left to refund." The payment was already refunded in full, or never captured
Pay Later or Venmo does not show PayPal decides by the buyer's country and currency; Venmo needs a US buyer paying in USD

See also

All Extensions