FleetbaseFleetbase
Start Free Trial

Wallet

Wallet endpoints expose the authenticated subject's balance and transaction history. Use wallets to retrieve current funds, inspect ledger activity, and initiate top-ups through a configured gateway.

The Wallet object

A wallet tracks the balance for the authenticated subject. Ledger stores monetary values in the smallest currency unit.
Attributes
idstringoptional

Public identifier of the wallet.

subject_uuidstringoptional

UUID of the model that owns the wallet.

subject_typestringoptional

Model class that owns the wallet.

subjectobjectoptional

Loaded wallet owner, when included.

namestringoptional

Wallet name.

descriptionstringoptional

Wallet description.

typestringoptional

Wallet type.

balanceintegeroptional

Wallet balance in the smallest currency unit.

formatted_balancestringoptional

Human-readable wallet balance.

currencycurrencyoptional

Wallet currency code.

statusstringoptional

Wallet status.

is_frozenbooleanoptional

Whether wallet activity is frozen.

metaobjectoptional

Arbitrary metadata stored with the wallet.

created_attimestampoptional

Time the wallet was created.

updated_attimestampoptional

Time the wallet was last updated.

The Wallet object
{
  "id": "wallet_2Tn8Qk1",
  "subject_uuid": "9c6292e4-9d7b-4ab4-94a1-3f4a11c1cf25",
  "subject_type": "Fleetbase\\Models\\User",
  "subject": null,
  "name": "Default wallet",
  "description": null,
  "type": "default",
  "balance": 5000,
  "formatted_balance": "50.00",
  "currency": "USD",
  "status": "active",
  "is_frozen": false,
  "meta": {},
  "created_at": "2026-05-07T09:30:00Z",
  "updated_at": "2026-05-07T09:30:00Z"
}
GET/v1/wallet

Get Wallet

Retrieves the authenticated subject's wallet. Pass a currency to choose the wallet currency when Fleetbase needs to provision one.

Query parameters
currencycurrencyoptional

Three-letter currency code for monetary values.

GET/v1/wallet
curl https://api.fleetbase.io/v1/wallet?currency=USD \
  -H "Authorization: Bearer flb_live_…"
GET/v1/wallet/balance

Get Wallet Balance

Returns the authenticated subject's wallet balance. Fleetbase provisions a wallet automatically when one does not already exist.

Query parameters
currencycurrencyoptional

Three-letter currency code for monetary values.

GET/v1/wallet/balance
curl https://api.fleetbase.io/v1/wallet/balance?currency=USD \
  -H "Authorization: Bearer flb_live_…"
GET/v1/wallet/transactions

List Wallet Transactions

Lists transactions for the authenticated subject's wallet. Results can be filtered by transaction type, direction, status, and creation date range.

Query parameters
typeenumoptional

Classification used to group or process the resource. One of customer, vendor, driver.

directionenumoptional

Direction value for this wallet request. One of credit, debit.

statusenumoptional

Lifecycle status to apply to the resource. One of active, inactive.

date_fromtimestampoptional

Date from value for this wallet request.

date_totimestampoptional

Date to value for this wallet request.

limitstringoptional

Limit value for this wallet request.

GET/v1/wallet/transactions
curl https://api.fleetbase.io/v1/wallet/transactions?type=&direction=&status=&date_from=&date_to=&limit=25 \
  -H "Authorization: Bearer flb_live_…"
POST/v1/wallet/topup

Top Up Wallet

Tops up the authenticated subject's wallet through a configured payment gateway. Amounts are submitted in the smallest currency unit.

Body parameters
gatewaystringrequired

Public ID or UUID of the payment gateway to charge.

amountintegerrequired

Top-up amount in the smallest currency unit. Must be at least 100.

payment_method_tokenstringoptional

Gateway payment method token, such as a Stripe pm_ token.

customer_idstringoptional

Customer ID from the payment gateway.

descriptionstringoptional

Description stored with the top-up payment. Maximum length is 500 characters.

POST/v1/wallet/topup
curl -X POST https://api.fleetbase.io/v1/wallet/topup \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "gateway": "{{gateway_id}}",
  "amount": 1000,
  "payment_method_token": "{{payment_method_token}}",
  "customer_id": "{{gateway_customer_id}}",
  "description": "Wallet top-up"
}'
Wallet | Fleetbase