Payments

In a deep integration you charge the rider, not Voi. Voi prices every ride and returns the amount when the ride ends; you collect it from your user with your own payment provider, and settle with Voi separately through invoicing. This page covers what you charge, what you owe, and who handles refunds.

How money moves

Charging the rider

Once per ride, in real time:

1. The user ends the ride — POST /v1/rental/{rentalId}/end.
2. Voi calculates the total price and returns it in the rental's cost object.
3. You charge the user that amount.

Voi commits to the price presented when the ride starts, but some exceptions can change it. The actual price is always returned when the ride ends — charge from that response rather than from the estimate you showed earlier.

Settling with Voi

Once per invoicing period:

1. You send Voi invoicing material: the rides charged, a list of refunded rides, VAT, and the total amount owed — broken down per day and per city.
2. Voi issues an invoice with any commission deducted, in the local currency of each city.
3. How often invoices are sent is defined in your contract with Voi.

Questions about invoices and settlement go to finance.

What the API returns

Ending a rental returns the full cost breakdown:

"cost": {
  "startPrice": 150,
  "pricePerMinute": 30,
  "subtotal": 429,
  "total": { "amount": 510, "currency": "EUR", "vat": 81, "vatPercentage": 0.19 }
}

Field	Description
startPrice	Unlock fee, incl. VAT
pricePerMinute	Per-minute fee, incl. VAT. Minutes are rounded up
subtotal	Total excluding VAT
total.amount	The amount to charge the user — the full ride cost, incl. VAT
total.currency	Three-letter currency code (ISO 4217) — the city's local currency
total.vat	VAT amount
total.vatPercentage	VAT rate, e.g. 0.19

In the example above the ride lasted 12 minutes, so startPrice + pricePerMinute × 12 = 150 + 360 = 510, which matches total.amount. subtotal is the same ride without VAT: 429 × 1.19 ≈ 510.

Amounts are in minor units

Every amount in the API is an integer in the currency's minor unit, not a decimal. Most currencies use 1/100, so { "amount": 510, "currency": "EUR" } is €5.10, not €510. Charging the raw integer is the most common mistake in a new integration.

Not every ride is charged

The rental's state tells you whether to charge:

State	Charge the user?
ENDED	Yes — the ride ended normally
ENDED_WITH_NO_CHARGE	No — the ride was auto-ended without a charge
ENDED_INTERNALLY	Yes — Voi ended the ride (for example the user forgot to); the returned total already reflects it

Receipts

The end-ride response includes receipt.url, a link to a PDF receipt. The link expires after 15 minutes, so download and store the file if you want to show the rider a receipt later.

Prices before the ride

To show a price up front, request it per vehicle with GET /v1/pricing/vehicle/{vehicleId}. Prices change over time and by location, so do not cache pricing — request it when the user needs it.

Prices and fees

Pricing is under active development and constantly evolving, but it typically consists of a fixed fee and a minute fee. The price is always returned so that you can charge the end users.

End-ride fines — If the user leaves the scooter without locking it, Voi will manually end the ride with a cost corresponding to the time when the scooter stopped moving, and send a warning to the user. If the user leaves the scooter unlocked again, we will also end the ride when the scooter stopped moving and add a fee of €25.

No charges after the ride — Voi does not charge for anything once the ride has ended. The €25 fine above is not an exception: it is added to the end-ride amount, so it reaches you in the same total as the rest of the ride.

Short rides — All rides are charged.

Rides before 1 January 2024

Rides shorter than 100 metres or 2 minutes were not charged. It was optional for the partner to present receipts for them or include them in invoicing material.

Refunds

The partner performs all refunds. When a refund is due is defined in the customer support criteria. Voi customer support also requests refunds from the partner from time to time; the method for those requests is agreed with your points of contact during onboarding.

Include refunded rides in the invoicing material for the period.

Fraud

The partner is responsible for making sure they can collect the money from the end user, including fraud prevention. Voi places no requirements on how you do this.