public-api-docs

User API Wallet, Balances, And Pricing Guide

Overview

The wallet is the user-facing view of balances, remaining voucher value, remaining minutes, payment methods, invoices, and balance history. The API returns both monetary value and minute-style value so each operator app can decide what to show: money, minutes, both, or a simplified benefit summary.

Use this guide for wallet screens, balance history, shared balances, top-up/package references, invoice shortcuts, and price preview surfaces.

Related reference: User API

User API Guide

Payments And Invoices Guide

Packages Guide

Vouchers And Promotions Guide

Wallet Display

Use GET /balances to list balances available to the authenticated user. You can filter by branchId or vehicleId when the wallet is shown in a specific rental context.

Important balance fields:

Field	Meaning	Wallet display idea
`name`	Balance name.	Wallet/account label.
`currency`	Balance currency.	Display with monetary values.
`value`	Current balance value.	Main wallet amount when the app shows money.
`remainingVouchersGrossValue`	Remaining gross value from voucher-style benefits.	Benefit credit summary.
`remainingMinutesValue`	Remaining minutes from minute-based benefits.	Free minutes or included minutes summary.
`defaultBalance`	Whether this is the user’s default balance.	Mark as default payment/balance source.

The API intentionally returns both value and minutes. Apps can decide the wallet design:

show only money for wallet-credit products,
show only minutes for minute-based mobility products,
show both in separate wallet rows,
show a compact “benefits available” summary and expose detail in a second screen.

Balance History

Use GET /balances/{balanceId}/history to show balance transactions. Add includeZeroValueUpdates=true only if the app needs audit-style entries that did not change value.

Balance history entries can reference:

a rental,
a booking,
a voucher,
a voucherable/package/subscription source,
a vehicle category,
a transaction type such as package, subscription, rental, top-up, correction, refund, reward, or collection invoice.

This is the right endpoint for “what changed my wallet?” screens. Use invoices for billing documents and payment status.

Shared Balances

Balances can be shared with other users where enabled.

Task	Endpoint
Create balance	`POST /balances`
Delete balance	`DELETE /balances/{id}`
Select default balance	`POST /balances/{id}/default`
List balance users	`GET /balances/{balanceId}/users`
Grant balance access	`POST /balances/{balanceId}/users`
Revoke access	`DELETE /balances/{balanceId}/users/{referralCode}`

Balance sharing should be explicit in the UI. Show who has access and re-fetch users after every grant/revoke action.

Payment Methods And Invoices

Wallet screens commonly link to payment method management and invoices:

Use the Payments And Invoices Guide for card, Stripe, Adyen, Apple Pay, Google Pay, PayPal, and invoice-payment flows.
Use GET /invoices?unpaid=true&invoicedOnly=true to show unpaid invoices that need user action.
Use POST /invoices/retry to retry payment for retryable unpaid invoices.
Use invoice lists/details when the user wants billing documents rather than wallet-balance transactions.

This separation matters: balance history explains wallet value movement; invoices explain billable documents, payment attempts, unpaid amounts, and receipts.

Pricing Calculators

Use pricing calculators for previews:

Flow	Endpoint
Pricing bundle or assignment estimate	`GET /pricing-bundles/pricing-calculator`
Specific pricing bundle simulation	`GET /pricing-bundles/pricing-simulator`
Booking estimate	`GET /booking-price-calculator`

PricingBundlePrice returns gross booking/total/addition prices. Booking price calculators return booking-specific price data. Treat all calculator output as an estimate until the rental or booking is created and priced.

Most Relevant APIs

Area	Endpoints
Wallet balances	`GET /balances`, `POST /balances`, `DELETE /balances/{id}`, `POST /balances/{id}/default`
Balance history	`GET /balances/{balanceId}/history`
Balance sharing	`GET/POST /balances/{balanceId}/users`, `DELETE /balances/{balanceId}/users/{referralCode}`
Payment methods	Payment-source endpoints in Payments And Invoices Guide
Invoices	`GET /invoices`, `POST /invoices/retry`
Pricing calculators	`GET /pricing-bundles/pricing-calculator`, `GET /pricing-bundles/pricing-simulator`, `GET /booking-price-calculator`

Implementation Notes

Decide upfront whether your wallet shows money, minutes, or both. The API returns enough data for either design.
Refresh balances after package purchase, voucher redemption, subscription purchase/renewal, rental end, invoice payment, or balance sharing changes.
Use balance history for wallet transactions and invoices for billing documents.
Link payment method management from the wallet when users need to fix failed payments or prepare for purchases.
Calculator results are previews; final charge and final benefit application happen in rental, booking, and invoice flows.