Next Inventory 6.1.0: App Manager, dark mode, and more Joomla 6.1 "Nyota" Is Here Building the Future of Joomla Extensions
NextSoftware
Next Restaurant — Documentation

PayPal

Card and PayPal-balance payments through PayPal's Orders v2 API — a redirect to PayPal, a capture on return, and a webhook backstop.

How the flow works

  1. The guest chooses PayPal at checkout.
  2. An order is created at PayPal and the guest is redirected to PayPal's approval page.
  3. On approval the guest returns to your site, the return is verified server-side, and the payment is captured.
  4. Independently, PayPal's webhook confirms the capture. If the guest never returns, the order settles from the webhook instead.

Creating and then explicitly capturing is PayPal's two-phase model; both halves happen server-side, so an abandoned return doesn't leave an approved-but-uncaptured order.

Setting it up

1. Create the gateway

Payment Gateways → New → PayPal. The form asks for PayPal's client credentials and the webhook identifier.

Start in sandbox mode with sandbox credentials.

2. Register the webhook at PayPal

Copy the webhook URL from the gateway configuration and register it in your PayPal developer dashboard, subscribing to the order and capture events. PayPal issues a webhook ID — put it in the gateway configuration so incoming webhooks can be verified.

3. Test

  1. Place a test order and pay with a PayPal sandbox account.
  2. Confirm the order settled in Payments with PayPal's capture reference.
  3. Issue a partial refund and confirm it appears in the PayPal dashboard.
  4. Place another test order and abandon the browser at PayPal's page. The order should settle shortly afterwards via the webhook.

4. Go live

Swap sandbox credentials for live ones, register the live webhook and its ID, and run one small real transaction.

Two things that will waste your afternoon

Both are PayPal's behaviour rather than Next Restaurant's, and both are worth knowing before you start:

PayPal's sandbox webhook verification is not a security test. The sandbox verification API has been observed approving forged signatures. That means a successful sandbox verification does not prove your production verification is sound — verify against live before trusting it, and never weaken verification because "the sandbox accepted it".

PayPal's sign-in page does not render in a headless browser. If you are scripting an end-to-end test, the PayPal approval step will not complete headlessly. Test that step manually, or stub it, and keep the automated coverage on your own return and webhook handlers.

Requirements

  • A PayPal business account.
  • HTTPS on your site.
  • A publicly reachable site for webhooks. On a local install, redirect payments only complete when the guest returns normally.

What is stored on your site

PayPal's order and capture references, the amount, the currency and the status. No card data — the guest authenticates and pays entirely on PayPal's side.

Your PayPal credentials are held in the gateway configuration and stripped from API responses. Re-entering a secret when editing the gateway is expected.

Troubleshooting

Symptom Cause
Guest approved but the order is unsettled The webhook isn't arriving, and the guest didn't return — check the endpoint and webhook ID
Webhook verification fails The webhook ID in the gateway doesn't match the one PayPal issued
Approved but not captured Capture failed after approval — check the payments ledger and PayPal's dashboard for the reason
Sandbox works, live doesn't Credentials, webhook and mode must all be live together
Headless test hangs at sign-in Expected — PayPal's sign-in doesn't render headlessly

See also

All Extensions