Order funds holds and expiry

Reference

An order reserves its cost in the tenant's wallet as soon as that cost is known, so the merchant knows the money is there before doing the work. The reservation is used for the payment when the order completes, given back when the order is cancelled, and lapses after a few hours — the order then waits as Expired until someone re-confirms it.

Overview#

A funds hold is a reservation of part of the tenant's wallet for one order. While it stands, that money cannot be spent on anything else, but it has not yet left the wallet. A purchase order holds its total from the moment it is created; a work order holds nothing until its cost is known. A hold can draw on the tenant's cash and on the tenant's platform credit line. An order carries at most one live hold at a time. The wallet itself — balance, history, top-ups — is described on Wallets and balances.

Statuses#

Every hold is in one of four states.

A hold never returns to Held. Re-confirming an expired order places a new hold rather than reviving the old one.

stateDiagram-v2
    state "Held" as held
    state "Captured" as captured
    state "Released" as released
    state "Expired" as expired
    [*] --> held: cost known and covered
    held --> captured: order completes
    held --> released: cancel, reject or cost change
    held --> expired: time runs out
    captured --> [*]
    released --> [*]
    expired --> [*]

When an order reserves funds#

Each time a hold is adjusted, the old reservation is released and the new one placed in one step, so a refused increase never leaves the order unheld. Re-declaring the same amount changes nothing and sends no second notification.

No hold: an order between a tenant and a merchant who settle through a B2B-Direct credit account holds nothing; the credit limit is enforced when the payment is taken. If the pair moves to B2B-Direct while an order still holds funds, that hold is released the next time the order's cost is checked. See B2B-Direct credit accounts.

Calculations#

What a tenant can spend on a new hold is worked out the same way everywhere — at every order check and in the wallet's Total Available figure:

• Cash available = wallet balance − cash already held, never below zero.
• Credit available = unused credit on the tenant's active platform credit line − credit already held, never below zero. It is zero when there is no active line, or when the line is blocked for being overdue or exhausted.
• Spendable = cash available + credit available.

A hold takes cash first and credit only for the remainder, and records both parts. A blocked credit line withdraws only the credit; the tenant's own cash stays spendable. Credit lines themselves are described on Platform credit lines.

Example: a wallet with 200 cash and an active line with 1,000 unused credit can hold an order of 500 — 200 from cash and 300 from credit.

Rules#

Release

• Cancelling a purchase, work or refuel order, a merchant's rejection and a supervisor's rejection release the order's hold at once.

Capture on completion

• Completing an order uses the hold it already carries; no new reservation is made.
• If the final amount is lower than the hold, only the final amount is taken and the rest is released. If it is higher, the hold is first topped up, and completion is refused if the wallet cannot cover the difference.
• Completion is refused when the order has no live hold — for example because it expired — and when the hold sits on a wallet that is no longer the tenant's active wallet.
• A work order with no cost cannot be completed.
• What happens to the money after capture is on Order-to-cash flow.

Expiry

• A purchase or work order hold lasts six hours by default; the platform can set a different window. Refuel holds also last six hours: a standard refuel hold's window is fixed, and PVoil refuel holds have their own window, six hours by default.
• The platform looks for lapsed holds every 15 minutes by default, so an order can show as Expired a little after its hold ran out. In that gap the money is already spendable again and the order cannot be completed; once it shows as Expired, re-confirm it.
• When a hold lapses, an order in Draft, Pending or In progress becomes Expired, and the order remembers the status it had. Expiry never cancels an order. A PVoil refuel order in Funds Held or Authorized expires the same way; see Refuelling at PVoil stations.
• A refuel order waiting for the station's invoice is not moved, and a Blocked refuel order holds nothing that could expire. See Refuel order statuses.
• An order waiting in Pending Tenant Confirmation keeps waiting: its hold lapses and the money returns, but the order is not moved. Approving a purchase or refuel order reserves its funds, and the approval is refused if the wallet cannot cover them. An approved work order goes to Pending without a new reservation; its cost is reserved when the merchant accepts it, and acceptance is refused if the wallet cannot cover it.
• An order already completed or cancelled is left alone, and a hold whose payment has already gone through is not expired.
• The tenant's owners, admins and supervisors, and the order's driver, receive an order-expired notification asking them to re-confirm. See Who sees and is notified about an order.

Re-confirmation

• Re-confirming places a new hold for the same amount on the same wallet, with a fresh window, and returns the order to exactly the status it had. The order is not re-priced.
• It is refused, and the order stays Expired, if the wallet can no longer cover the amount or is no longer the tenant's active wallet.
• Tenant Owners, Admins and Supervisors re-confirm expired purchase and work orders on the web. Expired refuel orders are re-confirmed by the driver, who can re-confirm all three order types in the Driver App. Merchants cannot re-confirm. Step by step: Re-confirm an expired order.

Refusals#

When a hold cannot be placed for a purchase order, a work order, or a merchant's confirmation of the quantity or cost, the action is refused and nothing is saved: a new order is not created, an edit is rolled back, and a merchant's acceptance is undone. A new refuel order is the exception: it is saved as Blocked. The apps tell four reasons apart:

In the Driver App a refused order keeps the filled-in form. In the Merchant App the refusal is presented as the tenant's wallet problem, not the merchant's. What to do: Resolve an order refused for insufficient funds.

Edge cases#

• A draft purchase order holds funds from creation, so a draft left untouched expires like any other order.
• An order can expire and be re-confirmed more than once.
• A PVoil refuel order that expired can still be settled and reach Completed when the fuel was really dispensed at the pump.

Related#

• Order-to-cash flow
• Purchase and work order statuses
• Re-confirm an expired order
• Resolve an order refused for insufficient funds
• Wallets and balances
• Platform credit lines