Contents
On this page

Payments - Plugixa Car Parking

The free plugin has one way to pay: Pay on arrival. The customer books online and pays at the car park, and you record the money on the booking when it is taken. Every payment and refund is kept in a ledger that you can read under Plugixa Car Parking -> Payments, in the Sales group of the sidebar.

Online payment is part of Pro: see Stripe PRO, PayPal PRO, Mollie PRO, Adyen PRO and Klarna PRO. All write to the same ledger, and all refund through the provider, so everything on this page applies to them too. With Stripe, a long stay can also be paid month by month: see Monthly payments PRO.

Pay on arrival

The Payments section of Settings

Open Plugixa Car Parking -> Settings -> Payments. The Pay on arrival card says: “The customer books now and pays at the car park. You record the payment on the booking when it is made.”

Field Default Notes
Let customers pay on arrival On Adds or removes offline in the enabled_gateways setting.
Instructions for the customer “Please pay on arrival at the parking entrance.” “Shown once a booking is placed, and on its summary.” Stored as offline_instructions. Plain text, line breaks kept.

Press Save when you are done. The Settings screen needs the plugixa_carparking_manage_settings capability. See Settings.

What the customer sees

  • With one way to pay, the booking form has no payment step. The instructions are shown on the confirmation step and again on the success screen.

  • With two or more ways to pay, the form adds a Payment step that lists them as a choice. The instructions appear when Pay on arrival is the one selected. A second method needs Pro.

    The Payment method choice in the booking form: Pay on arrival, Online payment (Adyen), Pay with Klarna, Online payment (Mollie) and Credit / debit card (Stripe)

  • On the booking summary, a booking that still owes money shows a Pay now box with one button per available method. Pressing Pay on arrival shows the instructions and charges nothing.

A way to pay is offered only when it is switched on and has what it needs to work. Pay on arrival needs nothing, so the switch alone decides.

What is saved

A pay-on-arrival booking is saved with the payment status Unpaid and with the status chosen in Settings -> Bookings -> Status of a new booking (Pending by default). Nothing is written to the ledger until you record a payment.

A pending booking holds its space for the time set in Hold an unconfirmed booking for (minutes), 30 by default, and then expires. For pay on arrival you will usually want new bookings to start as Confirmed, or the hold set to 0, so that a booking is not released before the customer arrives. See Availability.

Bookings with nothing to pay

There is no separate “free” payment method. A booking whose total is zero, for example after a 100% coupon, is saved like any other and stays Unpaid: the ledger marks a booking Paid only when its total is above zero and has been covered. Its summary shows no Pay now box because nothing is owed.

Recording a payment

A booking page scrolled to its notes, Payments panel and Message log panel

Open the booking from Plugixa Car Parking -> Bookings. The Payments panel shows four figures and the booking’s own ledger rows.

Figure Meaning
Booking total What the booking costs
Paid Completed payments less completed refunds
Refunded The sum of the booking’s completed refunds
Balance due Total less paid, never below zero

With no rows the panel says “Nothing has been paid on this booking yet.”

  1. Click Record payment.
  2. The dialog explains: “For money taken outside the booking form, such as cash on arrival or a bank transfer.”
  3. Amount is pre-filled with the balance due, and the line under it says how much “is still owed on this booking”. Change it to record a part payment.
  4. Click Record payment.
Rule Message
The amount must be a plain number with a dot for decimals “A number, with a dot for decimals.”
The amount must be above zero “The amount must be more than zero.”
A payment has no upper limit An overpaid booking shows a balance due of zero

A payment recorded by hand is saved as Completed, with Pay on arrival as its method and no transaction ID. The button is shown to users who hold both the edit and the create capability (plugixa_carparking_edit, plugixa_carparking_create).

Refunding a payment

The Refund dialog open over a booking, with the amount that can be refunded

In the same panel, each completed payment has a Refund button while the booking still holds money.

  1. Click Refund on the payment’s row.
  2. The dialog says the refund “is added to the ledger as a row of its own; the payment stays as it is.”
  3. Amount starts at the payment’s amount, or at what the booking still holds if that is less. The line under it reads “Up to … can be refunded on this booking.”
  4. Click Record refund.
Rule Message
Only a completed payment can be refunded, and a refund cannot be refunded “Only a completed payment can be refunded.”
A refund cannot exceed what the booking has been paid, less earlier refunds “A refund cannot be more than the booking has been paid (…).”
The booking must not be in the trash “This payment belongs to a booking that is in the trash or no longer exists. Restore the booking before refunding it.”
Nothing left to refund “This booking holds no money to refund.”
A refund sent with no amount, once the booking was refunded in full “This booking has already been refunded in full.”

The refund is recorded under the same method as the payment it answers. Refunding needs the edit capability.

A refund sent through the REST API with no amount refunds what is left of the payment: the whole payment, or less when the booking was already partly refunded.

Where the money goes

The payment was taken by What Record refund does
Pay on arrival, or recorded by hand Records the refund. Return the money yourself, in cash or by transfer
Stripe PRO Sends the refund to Stripe, then records it with Stripe’s refund id
PayPal PRO Sends the refund to PayPal, then records it with PayPal’s refund id
Mollie PRO Sends the refund to Mollie, then records it with Mollie’s refund id
Adyen PRO Sends the refund to Adyen, then records it with Adyen’s reference
Klarna PRO Sends the refund to Klarna, then records it with Klarna’s refund id

If the provider refuses the refund, nothing is recorded and the dialog shows “The refund was refused by the payment provider: …” followed by its reason. A refund made in the Stripe dashboard, on PayPal, in the Mollie dashboard or in the Adyen Customer Area reaches the ledger by itself, so it must not be recorded here as well. Klarna does not report refunds made in its portal: refund Klarna payments from the booking.

Reports that come after the payment

A provider can tell the site about a payment long after the customer has left. Since version 1.2.0 three of these reports are handled for you.

A payment that arrives after the hold ran out

A booking that is not paid in time expires, and its space is free for someone else. If the customer’s payment then arrives:

  • The space is still free: the payment confirms the booking, as before.
  • The space has gone to someone else: the booking stays Expired, so the space is never sold twice. The money stays on the booking’s Payments panel, the site is emailed, and the customer is told on the screen they come back to (see Coming back from an online payment). Refund them from the booking, or offer them another space.

A refund the provider fails to make

A provider can accept a refund and fail to pay it out later, for example when the customer’s card has been closed. The refund row is then marked Failed, the booking holds the money again, and the site is emailed. This covers Stripe, PayPal, Mollie and Adyen.

A booking’s Payments panel with an Adyen payment and a refund marked Failed, so the booking still holds the whole amount

A failed refund counts for nothing: Refunded stays at zero and the Refund button is back on the payment. Refund again once you know why it failed.

Disputes

When a customer’s bank disputes a payment (a chargeback), the site is emailed once, on every gateway that reports disputes: Stripe, PayPal, Mollie and Adyen. Nothing changes in the ledger. Answer the dispute in the provider’s dashboard before its deadline.

These three emails go to the address in Settings -> Notifications, even when booking emails are switched off, because someone has to act on them. Each is listed in the Message log.

Report Email subject
Late payment, space gone “Late payment needs attention: HL-…”
Refund failed “A refund failed: HL-…”
Dispute opened “A payment was disputed: HL-…”

All three are also announced through the plugixa_carparking_payment_notice action, as late_payment_no_space, refund_failed and dispute_opened. See For developers.

The ledger never changes

There is no way to edit or delete a ledger row. A payment entered by mistake is put right with a refund, which leaves both on record. For the same reason a booking with a completed payment or refund against it cannot be deleted permanently: “This booking has payments recorded against it, so it cannot be deleted permanently.” It can still be moved to the trash.

How a payment changes the booking

A booking’s paid state is always worked out from the ledger, each time a completed payment or refund is recorded.

Ledger says Payment status Booking status
Paid in full (and the total is above zero) Paid Paid
Something paid, less than the total Part paid Confirmed
Nothing held, and the booking was Paid or Confirmed Unpaid Refunded
Nothing held, any other status Unpaid Unchanged
A month of a monthly plan could not be taken PRO Overdue Unchanged

Overdue is added by monthly payments PRO. It holds until Stripe takes the month that failed, even when the money paid so far covers the total.

Three more things follow from this:

  • As soon as any money is held, the booking’s hold no longer expires.
  • When a booking becomes Paid in full, the Payment received email is sent to the customer, provided Send booking emails is on. A part payment sends nothing. See Emails.
  • If a booking is repriced after money was taken, its paid state is worked out again against the new total.

The Payments screen

The Payments ledger listing payments and refunds

Plugixa Car Parking -> Payments lists every row of the ledger, across all bookings, newest first.

Column What it shows
Date When the row was recorded
Booking The booking reference, linked to the booking
Method The way of paying, by its own name, such as Pay on arrival
Type Payment or Refund
Amount The amount. A refund is shown in red with a minus sign. A row in a currency other than the site’s carries its currency code.
Status Completed, Pending or Failed
Transaction ID The provider’s reference, when there is one

The search box matches the transaction ID (“Search by transaction ID…”). The list can be filtered by booking, gateway, type (full, deposit, balance, refund, and installment for a month of a monthly plan PRO), status and amount, and sorted by any column except the transaction ID. Method, Type and Transaction ID are optional columns.

The screen is read-only. It has no add button, no trash and no export: “Every payment and refund recorded against a booking is listed here. Record one from the booking it belongs to.” Reading it needs the view capability.

A row keeps the id of the method that took the money. If that method is no longer installed, for example after going from Pro back to free, the row stays and shows the id (stripe, paypal) in place of a name.

Coming back from an online payment

When a customer pays on a provider’s page PRO, the provider sends their browser back to your site. The plugin confirms the payment with the provider, records it, and redirects the customer to a page that says how it went. That page is chosen in this order:

  1. Booking page in Settings -> Bookings -> Pages
  2. Booking summary page in the same card
  3. The first published page that holds the booking form
  4. The home page, which cannot show the result

Choose at least one of the two pages. The screen replaces the booking form or the summary for that one visit and has four states.

The Payment received screen, with the booking reference

State Heading When
Paid Payment received The booking has money recorded against it
Confirming Confirming your payment The provider has not decided yet, or said paid before the booking is recorded as paid. “This can take a few minutes; there is no need to pay again.”
Too late Your payment arrived too late to hold the space The payment was recorded after the booking expired and its space had been taken. “We have been told and will contact you about a refund.”
Failed Payment not completed “The payment was cancelled or did not go through, and nothing has been charged.”

The Confirming your payment screen, with the booking reference and a Back to the booking form button

Since version 1.2.0, a customer who comes back while the provider is still deciding, which Mollie, Adyen and Klarna can take a moment to do, sees Confirming your payment instead of Payment not completed. Once the provider reports, the booking is updated by itself.

The Your payment arrived too late to hold the space screen, with the booking reference and a Start a new booking button

The Payment not completed screen, with the booking reference and a note that the booking is saved but unpaid

A customer who leaves the provider’s page with its own back or cancel link also lands on Payment not completed, with a Start a new booking button.

The screen shows Your reference when the address names a real booking and carries that booking’s payment key, on the failed screen too. What is shown is read from the booking, not from the address, so a link with “paid” typed into it proves nothing. On the failed screen a note says where the booking stands: saved but unpaid, already paid in full, cancelled, or expired because it was not paid in time.

The payment key

Since version 1.1.0, a booking reference alone opens nothing. Starting a payment, and the screen shown on the way back, both need the booking’s payment key as well, which works like a WooCommerce order key. The key is given only to whoever made the booking or holds its summary link, and travels in the addresses handed to the provider, as plugixa_carparking_key.

Without it, somebody who guessed a reference could open a provider’s checkout for the booking, which shows the customer’s email, or learn whether it is paid. A wrong key is answered as if the booking did not exist.

Nothing needs setting up. An address without the key, such as one saved before 1.1.0, still shows the screen, but without the reference, and a paid one reads Confirming your payment because the booking cannot be read.

Kept out of search engines

The booking summary page, and any page whose address carries a booking reference, a summary token, a payment key or a payment result, is sent with noindex, nofollow, noarchive. A customer’s booking never ends up in search results, whatever SEO plugin the site uses.

Kept out of page caches

Since version 1.2.0, the summary link and the screen a customer sees after paying are sent with no-cache headers and the DONOTCACHEPAGE signal, which WP Super Cache, W3 Total Cache, WP Rocket and LiteSpeed Cache all honour. A customer is never shown a stale payment status, or another customer’s booking on a cache set to ignore the address.

The booking form, the summary page with nothing in its address and the account page stay cacheable, because they are the same for every signed-out visitor.

Public payment routes

Three public REST routes serve payments. They exist in the free plugin, where only pay on arrival answers them.

Route Method Purpose
/plugixa-car-parking/v1/payment/start POST Begin a payment for a booking reference and its payment key (booking_ref, booking_key), with a chosen method
/plugixa-car-parking/v1/payment/return GET, POST Where a provider sends the customer’s browser back to
/plugixa-car-parking/v1/payment/webhook/<gateway> POST Where a provider reports a payment server to server

The return and webhook routes are also answered at the older address, /plugixacarparking/v1/payment/return and /plugixacarparking/v1/payment/webhook/<gateway>. Those are the addresses the plugin hands to payment providers, and they are kept for good because a provider’s dashboard is somewhere an update cannot reach.

  • Start is rate limited to 20 requests an hour per IP address and needs the form’s security token. A method that is off or not configured is refused with “That payment method is unavailable.”
  • Return and webhook are not rate limited: a refused call there would be a payment your site never hears about. They rely on the gateway, which confirms a return with the provider and checks a webhook’s signature before anything is recorded.
  • A webhook the gateway does not accept is acknowledged and ignored. The answer is 200 for a known gateway, so nothing is revealed and the provider stops retrying.
  • A webhook the gateway accepted but that could not be written at that moment, because another report for the same booking held it, is answered 503. The provider sends it again.

One payment is recorded once

An online payment is reported twice by design: by the customer’s return and by the webhook, often in the same second. A refund made from the booking is reported back by the webhook too. Each report is written under a lock held per booking, and a completed transaction whose provider reference is already in the ledger is not written again. The same holds for a refund and for a failed attempt. The booking is marked paid once and the Payment received email is sent once.

What is stored

Payments live in the {prefix}plugixacarparking_payments table: the booking, the gateway id, the provider’s transaction ID, the type (full, deposit, balance, refund, or installment PRO), the amount, the currency, the status (completed, pending or failed) and what the provider reported. See Privacy and uninstall.

For developers

Hook Type Purpose
plugixa_carparking_register_gateways action Register another payment gateway
plugixa_carparking_payment_charge filter Decide what a customer is charged when a payment starts
plugixa_carparking_payment_recorded action React after a booking’s paid state has been worked out again
plugixa_carparking_payment_notice action React to a provider report that moves no money: a checkout left to expire, a payment still processing, a refund that failed, a dispute opened or closed

See Hooks reference and REST API.

Quick Links

Share