Contents
On this page

PayPal - Plugixa Car Parking

PayPal PRO is a payment method that sends the customer to PayPal to approve the payment and brings them back to your site, where the money is captured. Customers see it as PayPal.

Set it up under Plugixa Car Parking -> Settings -> PayPal. Everything on Payments about the ledger, refunds and booking statuses applies to PayPal payments too.

Setting it up

The PayPal settings: client ID, secret, sandbox switch, and the webhook address, events to send and Webhook ID

The PayPal card says: “The customer approves the payment on PayPal and is brought back to the booking. The credentials are those of a REST app in the PayPal developer dashboard.”

  1. In the PayPal developer dashboard, create a REST app. It gives you a client ID and a secret, one pair for the sandbox and one for live.
  2. Open Plugixa Car Parking -> Settings -> PayPal and fill in the fields below.
  3. Add the webhook, as described under Adding the webhook.
  4. Press Save.
Field Key Default Notes
Offer payment by PayPal paypal in enabled_gateways Off The switch that offers PayPal to customers.
Client ID paypal_client_id Empty Stored as plain text.
Secret paypal_secret Empty Stored encrypted and never sent back to the browser.
Use the PayPal sandbox paypal_sandbox On “For testing: no real money moves. The client ID and secret must be the sandbox app’s.”
Webhook ID paypal_webhook_id Empty Stored as plain text. “Without it no event can be verified, so every event is ignored.”

PayPal is offered to customers only when the switch is on and both the client ID and the secret are stored. Otherwise the screen warns: “PayPal is switched on but needs both a client ID and a secret before a payment can start.”

Adding the webhook

The second card is Webhook: “Lets PayPal confirm a payment server to server, and tells the site about refunds made on PayPal and disputes.”

  1. Copy the Webhook address shown on the card. It has this form:

    https://example.com/wp-json/plugixacarparking/v1/payment/webhook/paypal
    
  2. In your REST app in the PayPal developer dashboard, add a webhook with that address.

  3. Subscribe it to the events listed under Events to send on the card:

    Event What the plugin does
    PAYMENT.CAPTURE.COMPLETED Records the payment, with its type (whole, deposit or balance)
    PAYMENT.CAPTURE.DENIED Records a Failed row; the booking stays unpaid
    PAYMENT.CAPTURE.PENDING Nothing recorded; announced. The money is recorded when the capture completes
    PAYMENT.CAPTURE.REFUNDED Records a refund made on PayPal once it has completed
    PAYMENT.CAPTURE.REVERSED Records the money PayPal took back as a refund
    CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.RESOLVED Nothing recorded; announced
    CHECKOUT.ORDER.APPROVED Accepted and ignored in version 1.0.1. Subscribe to it anyway, so nothing needs changing later

    “Announced” means the action plugixa_carparking_payment_notice fires with payment_processing, refund_failed, dispute_opened or dispute_closed, so an add-on or a snippet can email you about it. The site is also emailed about a dispute_opened.

  4. PayPal shows the new webhook with a Webhook ID. Paste it into Webhook ID and press Save.

The sandbox app and the live app each have their own webhooks, so each has its own Webhook ID. Always copy the address from the screen. It is built from your site’s own REST address, so it is right on a site with plain permalinks too.

Without a Webhook ID

Every event is ignored: anyone can post to the address, and without the ID the plugin cannot ask PayPal whether an event is genuine. Payments are then confirmed only when the customer returns to your site, and refunds or reversals made on PayPal are not recorded. Set the Webhook ID.

With the ID set, each event is checked with PayPal’s verify-webhook-signature API before anything is recorded. An event PayPal does not confirm is ignored and answered 200, so PayPal stops retrying. An event the plugin accepted but could not write at that moment (another report for the same booking held it) is answered 503, and PayPal sends it again.

Sandbox and live

Use the PayPal sandbox is on for a new install, so a fresh set-up takes no real money.

Switch The plugin talks to Credentials to enter
On https://api-m.sandbox.paypal.com The sandbox app’s client ID and secret
Off https://api-m.paypal.com The live app’s client ID and secret

To go live, switch the sandbox off and replace both credentials with the live app’s. Sandbox credentials against the live address, or the reverse, fail to sign in, and the customer sees “PayPal authentication failed.”

What the customer sees

  1. With PayPal and another method both on, the booking form shows a Payment step where the customer chooses. With PayPal as the only method, the step is left out.
  2. On confirming, the booking is saved first, then the customer is sent to PayPal.
  3. PayPal shows the payment as “Parking booking” followed by the booking reference, with a pay-now button.
  4. After approving, the customer returns to your site, the payment is captured, and they see Payment received. See Coming back from an online payment.

A customer can also pay later from the booking summary, which shows a Pay now box with a PayPal button while anything is still owed.

If the payment cannot be started, the booking still exists. The confirmation says “Your booking is saved, but the payment could not be started.” followed by the reason.

How a payment is confirmed

The plugin uses PayPal’s Orders API in two steps.

Step When What happens
Create The customer confirms the booking The plugin signs in to PayPal with your credentials and creates an order for the amount due, to be captured
Capture PayPal sends the customer’s browser back to your site The plugin captures the order. If PayPal answers that the capture is completed, the payment is recorded
Confirm PayPal posts PAYMENT.CAPTURE.COMPLETED to the webhook The same capture is recognised and not recorded again

The amount recorded is the amount PayPal reports it captured. The row appears in Plugixa Car Parking -> Payments with the method PayPal, the status Completed and PayPal’s capture id as its transaction ID. A capture that is reported a second time is not recorded again.

A capture PayPal holds back (an eCheck, a review) completes the order but not the payment. Nothing is recorded on return; the webhook records the payment once PayPal releases the money.

Payments missed by version 1.0.0. Version 1.0.0 could take a PayPal payment without recording it on the booking. When the customer opens their PayPal return link for that order again, version 1.0.1 finds the capture and records it, and it can then be refunded through PayPal like any other.

The money is taken only when the customer comes back. Approval at PayPal does not move money by itself. If the customer approves and then closes the window before PayPal returns them to your site, nothing is captured, nothing is charged, and the booking stays unpaid. They can pay again from the booking summary.

Unpaid and abandoned payments

The booking exists before the customer pays, as Pending and Unpaid with default settings. If the customer does not finish at PayPal, the booking keeps its space until its hold runs out (Hold an unconfirmed booking for (minutes), 30 by default) and then expires. See Availability.

A customer who cancels on the PayPal page is returned to your booking page and sees the Payment not completed screen with their booking reference. The booking stays saved and unpaid, and can be paid from its summary. See Coming back from an online payment.

Amounts and currencies

  • The currency is the booking’s own, which is the Currency code in Settings -> General. It must be a currency your PayPal account accepts.
  • The amount is sent with two decimal places.
  • With Deposits PRO, the amount sent is the part due now, and the payment is recorded with its type (deposit or balance).

Refunds

A refund of a PayPal payment made from the booking’s Payments panel is sent to PayPal first and recorded with PayPal’s refund id. If PayPal refuses it, nothing is recorded and the error is shown: “The refund was refused by the payment provider: …” PayPal then reports the same refund to the webhook, and it is recognised and not recorded twice. See Refunding a payment.

A refund made on PayPal, or a reversal, arrives by webhook and is recorded against the booking whose payment it refunds. A refund larger than what the booking still holds is recorded as what it holds, with the amount PayPal reported kept on the row.

If the client ID or secret has since been removed, a PayPal payment cannot be refunded from the booking (switching PayPal off for customers does not stop refunds): “This payment was taken online, but the payment method is no longer set up, so it cannot be refunded from here.”

What is sent to PayPal

The plugin talks to PayPal from your server: when a customer starts a PayPal payment or returns from one, when you refund a PayPal payment, and to verify each webhook event. There is no PayPal script on your pages.

Sent
Client ID and secret To sign in. The sign-in token is kept until shortly before it expires
Amount and currency The amount due now
Booking reference and payment type As the order’s custom id; the reference also in its description
Return and cancel addresses On your site
Webhook ID and the event To verify an event PayPal sent

No name, email address, phone number or licence plate is sent by the plugin. What the customer enters at PayPal goes to PayPal directly. See Privacy and uninstall.

If Pro is removed

The client ID, the encrypted secret and the Webhook ID stay in the settings and are live again when Pro is reinstalled. PayPal is no longer offered to customers, and existing PayPal rows stay in the ledger with paypal shown as their method. See Free vs Pro.

Quick Links

Share