Refuelling at PVoil stations

Reference

At a PVoil station the driver scans a QR that the pump terminal generates for this fill. The platform first holds money in the company wallet, sends the payment request to PVoil, and completes the order in the background with the volume and amount PVoil reports.

Overview#

PVoil's pump terminal generates a QR for each transaction that carries the product, the volume and the amount. The driver picks the PVoil station and enters the odometer; the platform holds money in the company wallet and opens the camera; the driver scans the QR, and the platform reads it and sends the payment request to PVoil. PVoil's confirmation completes the order later. The driver never waits for PVoil: the app can be closed and reopened at any point, and the platform keeps the order's status. There is no pump photo in this flow. The general fields of a refuel order are on Refuel orders.

Rules#

Starting the order and the wallet hold#

1. The driver's current vehicle is used. The odometer reading is optional, and a photo can be used to fill it in.
2. The platform checks the vehicle's refuel limit. When the limit allows nothing (allowance used up, tank full, or no recent GPS), the order is created as Blocked with no money held, and the driver can ask a supervisor for approval. Trying again with the same vehicle while an order is Blocked reopens that order. An approval places the hold for the approved quantity and continues the flow; when the wallet cannot cover it, the approval fails. See Blocked refuels and supervisor approval.
3. Otherwise the platform holds the allowed quantity × the government price of the vehicle's fuel in the company wallet. The hold is placed silently, with no preview, and the app goes straight to the camera.
4. When the wallet does not have enough available, no order is started and the app shows Insufficient wallet balance — top up to continue. with the amount needed and the amount available.
5. The order is now Funds Held. The hold lasts six hours by default; what happens when it lapses is on Order funds holds and expiry.

The refuel limit is described on Refuel limits.

Scanning the PVoil QR#

When the driver scans the pump's QR, the platform reads it and pairs it with the order:

• Only an order that is Funds Held and not yet paired can be paired.
• Each PVoil QR can pair with only one order; a QR already used is refused, and the driver asks the attendant for a new one.
• The PVoil product on the QR must be a fuel item the merchant has set up, and that fuel must be allowed for the vehicle. Otherwise the scan is refused and the driver can only cancel the order; it cannot be rescanned.
• The station the driver picked counts. If the station name on the QR does not match it, the platform records the difference for follow-up and the order goes ahead.

A successful scan makes the order Authorized and queues the payment request to PVoil; no money leaves the wallet until PVoil confirms the fill. The app then shows Confirm refuel? with the vehicle and station, and the fuel type, volume and amount from the QR; PVoil's own reference numbers are never shown. After Confirm, the app shows Authorized — you may leave with the same summary. If the app is reopened later, that screen shows only the vehicle and station, with a note that the volume and amount appear in History once the refuel completes.

Completion and settlement#

PVoil confirms each payment back to the platform; the platform also checks with PVoil on a schedule, and both paths finish the order the same way, once. On completion:

• The order becomes Completed with the volume, unit price and amount PVoil reports.
• When the hold is still active, the wallet is charged the actual amount, capped at the amount held. When the hold had already lapsed, the order still completes, and the charge is left for back-office follow-up.
• If recording the charge fails, the order still completes and the charge is retried in the background.
• The filled litres are added to the vehicle's running tank estimate; see Fuel in tank and consumption norms.

The driver gets no notification when a PVoil refuel completes.

Cancellation#

• The driver can cancel an order that is Funds Held, Authorized or Expired; the hold is released. Leaving the camera asks Cancel scan? and warns that the reserved funds will be released.
• A Blocked order cancels with nothing to release.
• Cancel in Confirm refuel? cancels the order and returns the driver to the scan screen to start again.
• When PVoil cancels or voids the transaction, the order becomes Cancelled, the hold is released, and the driver and the company's admins get a push notification.

Statuses#

stateDiagram-v2
    state "Blocked" as blocked
    state "Funds Held" as held
    state "Authorized" as authorized
    state "Completed" as completed
    state "Cancelled" as cancelled
    state "Expired" as expired
    [*] --> held: hold placed
    [*] --> blocked: no allowance left
    held --> authorized: QR scanned
    authorized --> completed: PVoil confirms
    authorized --> cancelled: PVoil cancels or driver cancels
    held --> cancelled: driver cancels
    held --> expired: hold lapses
    authorized --> expired: hold lapses
    expired --> completed: fuel was dispensed
    expired --> cancelled: driver or PVoil cancels
    blocked --> held: supervisor approves
    blocked --> cancelled: rejected or cancelled

Related#

• Refuel at a PVoil station
• Refuel order statuses
• Refuel limits
• Order funds holds and expiry