Wallet API

Developer reference for the Wallet app. Server exports let another resource read a player’s cards, show one to a nearby player, issue and revoke membership cards and set the ID photo. Below the exports: the callbacks the phone itself uses, the two client events, the card schema and the Events app callbacks.

Three ways to get a card into a player’s wallet from your own resource:

A condition card in Config.Wallet.Cards — give an item, a license or a job grade and the card appears on the next open. No code.
issueWalletCard — a membership card with label, business, colour and expiry, for online and offline players.
Code inside the roadphone resource (server/serverAPI/*.lua, addons) may call the global functions directly.

Call the exports from a thread — a command handler, an event handler or CreateThread. Building cards runs synchronous queries.

Return shape

Write exports return a table:

{ ok = true,  id = 12, … }
{ ok = false, error = 'too_far' }

Error	Export	Meaning
`invalid_player`	showWalletCard	No player with that server ID is online
`invalid_target`	issueWalletCard, setWalletPhoto	Not an online server ID and not a non-empty identifier
`holder_name_required`	issueWalletCard	The target is offline and `holderName` was not given
`bad_job`	issueWalletCard	`business` missing or longer than 60 characters
`bad_label`	issueWalletCard	`label` missing, shorter than 2 or longer than 60 characters
`bad_color`	issueWalletCard	`color` is not `#RRGGBB`
`bad_expiry`	issueWalletCard	`expiresAt` lies in the past
`db_error`	issueWalletCard, setWalletPhoto	The query failed
`not_found`	revokeWalletCard	No active card with that id
`bad_target`	showWalletCard	Unknown, offline or own server id
`too_far`	showWalletCard	Distance above `Config.Wallet.ShowRadius`, or different routing buckets
`no_card`	showWalletCard	The player holds no card with that id right now
`bad_url`	setWalletPhoto	Not an `http(s)://` URL, or longer than 255 characters

Reading

getWalletCards

Every card of an online player, built live from the framework and the wallet tables.

local cards = exports['roadphone']:getWalletCards(source)

number

required

The player’s server ID.

table

Array of card objects. Empty when the player is offline or has no identifier.

for _, card in ipairs(exports['roadphone']:getWalletCards(source)) do
    print(('%s: %s (%s)'):format(card.type, card.title, card.meta.valid and 'valid' or 'expired'))
end

getWalletCard

One card by id.

local card = exports['roadphone']:getWalletCard(source, cardId)

number

required

The player’s server ID.

string

required

'id', 'license:<id>', 'job', 'gang', 'custom:<id>', 'member:<row id>' or 'ticket:<row id>'.

table | nil

The card object, or nil when the player does not hold it.

hasWalletCard

Does the player hold this card right now? The cheapest way to gate something on a license, a pass or a job card.

local allowed = exports['roadphone']:hasWalletCard(source, cardId)

number

required

The player’s server ID.

string

required

A card id, see getWalletCard.

boolean

true when the card exists for the player at this moment.

if not exports['roadphone']:hasWalletCard(source, 'custom:gym') then
    Notify(source, 'Members only.')
    return
end
OpenDoor('gym_main')

getWalletMemberships

Active membership cards (rows of roadshop_wallet_cards that are not revoked), newest first. Expired cards are included with valid = false.

local cards = exports['roadphone']:getWalletMemberships(target, business)

number | string

required

A server ID (online player) or an identifier string (the player may be offline).

string

Only cards issued under this business name. Omit for all.

table

{
    { id = 12, identifier = 'license:…', holderName = 'John Doe', job = 'gym', label = 'Gold',
      color = '#FF9F0A', issuedBy = 'Gym Script', createdAt = 1789459200, expiresAt = 1792051200, valid = true },
}

Membership cards

issueWalletCard

Issue a membership card. The holder gets a notification and their wallet refreshes while they are online; an offline player finds the card on the next open.

local result = exports['roadphone']:issueWalletCard(target, options)

number | string

required

A server ID (online player) or an identifier string. The identifier must be the one RoadPhone stores for the character: xPlayer.identifier on ESX, citizenid on QBCore / Qbox.

table

required

Show properties

string

required

Card title, 2–60 characters (Gold Member, VIP, Staff).

string

required

Issuing business, 1–60 characters. Shown as Business on the card. The Business tab of the Events app lists the card when this equals the boss’s job name. job is accepted as an alias.

string

#RRGGBB. Default green.

number

Valid for this many days from now. Omit for unlimited.

number

Unix timestamp of the expiry; takes precedence over days. Must lie in the future.

string

Shown as Issued by, up to 80 characters.

string

Name printed on the card. Required when the target is an identifier of an offline player; defaults to the online player’s name.

table

{ ok = true, id = number, expiresAt = number | nil } or { ok = false, error = string }. Keep id — it is what revokeWalletCard needs.

local result = exports['roadphone']:issueWalletCard(source, {
    label    = 'Gold Member',
    business = 'nightclub',
    color    = '#BF5AF2',
    days     = 30,
    issuedBy = 'Club Management',
})

if result.ok then
    SaveMembership(source, result.id, result.expiresAt)
else
    print('Could not issue card: ' .. result.error)
end

exports['roadphone']:issueWalletCard('ABC12345', {
    label      = 'Staff',
    business   = 'nightclub',
    holderName = 'Jane Roe',
})

revokeWalletCard

Revoke a membership card. The row stays for the records (revoked = 1); the card leaves the holder’s wallet immediately when they are online.

local result = exports['roadphone']:revokeWalletCard(cardId)

number

required

The id returned by issueWalletCard or listed by getWalletMemberships.

table

{ ok = true, id = number, identifier = string } or { ok = false, error = 'not_found' } (unknown id or already revoked).

for _, card in ipairs(exports['roadphone']:getWalletMemberships(source, 'nightclub')) do
    exports['roadphone']:revokeWalletCard(card.id)
end

Showing and photos

showWalletCard

Show one of a player’s cards to another player nearby — the same flow as the Show button, without the per-player rate limit. Use it for scripted ID checks.

local result = exports['roadphone']:showWalletCard(source, target, cardId, options)

number

required

Server ID of the card holder.

number

required

Server ID of the receiver. Must be within Config.Wallet.ShowRadius and in the same routing bucket.

string

required

A card id the holder owns right now.

table

Show properties

number

Seconds the card stays on the receiver’s phone, clamped to 1–120. Defaults to Config.Wallet.ShowDuration.

string

Sender label shown to the receiver. Defaults to the holder’s name.

table

{ ok = true, showId = number, duration = number } or { ok = false, error = string }.

RegisterServerEvent('police:requestLicense')
AddEventHandler('police:requestLicense', function(driver)
    local officer = source
    local result = exports['roadphone']:showWalletCard(driver, officer, 'license:drive', { duration = 60 })
    if not result.ok then
        Notify(officer, result.error == 'no_card' and 'No driver\'s license.' or 'Driver out of reach.')
    end
end)

setWalletPhoto

Set or clear the ID photo of a character — for example from a character creator or a mugshot system.

local result = exports['roadphone']:setWalletPhoto(target, url)

number | string

required

A server ID or an identifier string.

string | nil

required

An http(s):// URL of at most 255 characters, or nil to remove the photo (the app then offers Take photo again).

table

{ ok = true, photo = string | nil } or { ok = false, error = string }.

The export trusts the URL you pass. Only the in-app capture is restricted to the upload host allow-list, because that URL comes from the client.

refreshWallet

Tell an online player’s phone to reload its cards. Needed only after you changed something the Wallet reads that is not covered by the exports above — for example a Config.Wallet.Cards condition that flipped through your own inventory code.

exports['roadphone']:refreshWallet(source)

number

required

The player’s server ID.

boolean

true when the player is online.

Callbacks

Registered in server/wallet.lua. The phone calls them through the NUI proxies listed further down; the server never trusts a player id or identifier from the client — every distance is measured server-side and every identity is re-read from the framework.

Callback	Input	Returns	Description
`roadphone:wallet:getCards`	—	`{ ok = true, cards, profile = { photo } }`	Builds every card of the caller. Also credits pending Events money (refunds, payouts) first.
`roadphone:wallet:setPhoto`	`url`	`{ ok = true, photo }`	Stores the ID photo URL. Rate-limited to one call per 3 s; the host must be on the upload allow-list.
`roadphone:wallet:getNearby`	`serverIds` (max 32)	array of `{ playerId, name, distance }`	Filters the candidates to players within `ShowRadius + 2 m` in the same routing bucket, sorted by distance.
`roadphone:wallet:show`	`cardId, playerId`	`{ ok = true, showId, duration }`	Shows one card to one player within `ShowRadius`. Rate-limited to one show per 2 s.
`roadphone:wallet:checkIn`	`code`	`{ ok = true, checkedIn }`	Checks a ticket in. Only the event owner, only while the event is active, only within `ShowRadius` of the holder. Rate-limited to two calls per second.

Every failure answers { ok = false, reason = … }:

Reason	Callback	Meaning
`no_identifier`	all	The framework returned no identifier for the caller
`db_error`	all	A query failed; the console shows a `[Wallet]` traceback
`rate_limited`	setPhoto, show, checkIn	Called again too quickly
`bad_url`	setPhoto	Not a string, longer than 255 characters, or a host outside the upload allow-list
`bad_target`	show	Unknown, offline or own server id
`too_far`	show, checkIn	Distance above `Config.Wallet.ShowRadius`, or different routing buckets
`no_card`	show	The caller holds no card with that id right now
`bad_code`	checkIn	Not a string or longer than 12 characters
`not_found`	checkIn	No ticket with that code
`not_owner`	checkIn	The caller does not own the ticket’s event
`event_over`	checkIn	The event is cancelled, ended or past its end time
`already_checked_in`	checkIn	Already stamped; `checkedIn` carries the timestamp
`bad_request`	checkIn	The caller’s identity changed during the request

Client events

Event	Payload	Description
`roadphone:wallet:incoming`	`{ showId, card, from, expiresAt, duration, canCheckIn }`	A card is being shown to this player. `card` is a full card object; `from` is the sender label; `canCheckIn` is `true` only when the receiver owns the shown ticket’s event.
`roadphone:wallet:cardsChanged`	—	The player’s cards changed. The phone reloads the list when the Wallet is open or has been loaded this session.

Both are networked client events (RegisterNetEvent). refreshWallet triggers the second one for you; do not trigger roadphone:wallet:incoming yourself — the phone treats its payload as an already-verified card, the checks live in showWalletCard.

NUI callbacks

Registered in client/wallet.lua, for reference when you read the phone UI or write a custom app that reuses the flow.

NUI callback	Forwards to	Notes
`walletGetCards`	`roadphone:wallet:getCards`
`walletShowCard`	`roadphone:wallet:show`	`{ cardId, playerId }`
`walletSavePhoto`	`roadphone:wallet:setPhoto`	`{ url }`
`walletCheckIn`	`roadphone:wallet:checkIn`	`{ code }`
`walletGetNearby`	`roadphone:wallet:getNearby`	The client collects the server ids of players within `ShowRadius + 2 m` first
`walletSetRoute`	—	`{ x, y }` → `SetNewWaypoint`; used by the Route button of ticket cards
`walletRenderPhoto`	—	Renders a transparent ped headshot and answers `{ txd }`; the NUI loads it from `nui-img://`
`walletPhotoDone`	—	Releases the headshot handle once the NUI has read the texture

Card schema

Every card — from the exports, from getCards and in roadphone:wallet:incoming — has this shape:

{
    id       = 'member:7',            -- 'id' | 'license:<id>' | 'job' | 'gang' | 'custom:<id>' | 'member:<row id>' | 'ticket:<row id>'
    type     = 'member',              -- id | license | job | gang | custom | member | ticket
    title    = 'Gym Member',          -- locale key or plain text
    subtitle = 'gym',                 -- name of the holder, the business, or the ticket code
    color    = '#30D158',             -- #RRGGBB
    icon     = 'solar:medal-star-bold',
    photo    = nil,                   -- profile photo URL on id / job / gang cards
    fields   = {                      -- rendered in order
        { label = 'WALLET_FIELD_BUSINESS',  value = 'gym' },
        { label = 'WALLET_FIELD_HOLDER',    value = 'John Doe' },
        { label = 'WALLET_FIELD_ISSUED_BY', value = 'Jane Boss' },
        { label = 'WALLET_FIELD_ISSUED',    value = 1789459200, kind = 'date' },
        { label = 'WALLET_FIELD_EXPIRES',   value = 1792051200, kind = 'date' },
    },
    meta = { issued = 1789459200, expires = 1792051200, valid = true },
}

meta per type:

Type	`meta`
`id`, `license`	`number` (8-digit ID number), `valid = true`
`job`, `gang`, `custom`	`valid = true`
`member`	`issued`, `expires` (unix seconds or `nil`), `valid`
`ticket`	`number` (code), `valid`, `status` (`valid` / `checkedIn` / `expired`), `checkedIn`, `eventId`, `starts`, `ends`, `x`, `y`

Field kind values: date, datetime (unix seconds), dob (YYYY-MM-DD), sex (m / f), height (centimetres); without kind the value is shown as text.

Global functions (inside the `roadphone` resource)

Plain globals of server/wallet.lua — the same functions the exports wrap. They are not exports; use them from server/serverAPI/*.lua, addons or other scripts that run inside the resource. They return reason instead of error on failure.

Function	Export equivalent
`BuildWalletCards(source)`	`getWalletCards`
`BuildWalletCard(source, cardId)` → `card, internal`	`getWalletCard` (the second value carries ticket ownership info and never reaches the phone)
`WalletShowCard(source, target, cardId, opts)`	`showWalletCard`
`WalletIssueCard(identifier, holderName, { job, label, color, expiresAt, issuedBy })`	`issueWalletCard`
`WalletRevokeCard(cardId, { job })` — `job` limits the revoke to that business	`revokeWalletCard`
`WalletGetMemberships(identifier, job)`	`getWalletMemberships`
`WalletNotifyCardsChanged(source)`	`refreshWallet`
`WalletDistance(sourceA, sourceB)` → metres or `nil`	—

The boss actions of the Events app (Business tab) go through WalletIssueCard and WalletRevokeCard as well, so a card issued by a boss and a card issued by your resource behave the same.

Events app callbacks

The Events app supplies the tickets and membership cards the Wallet shows. Registered in server/events.lua; every one answers { ok = false, reason = … } on failure.

Callback	Input	Returns	Description
`roadphone:events:list`	—	`{ ok, events, isBoss, canCreate, limits }`	Upcoming events plus the caller’s permissions and `Config.Events` limits
`roadphone:events:mine`	—	`{ ok, events }`	Events the caller created or holds tickets for
`roadphone:events:get`	`id`	`{ ok, event, maxTicketsPerBuyer }`	One event with the caller’s ticket count
`roadphone:events:create`	`data`	`{ ok, id }`	Creates an event; charges `Config.Events.CreateFee`, honours `RequireJob`, `MaxPrice`, `MaxCapacity`, `MaxActivePerPlayer`
`roadphone:events:buy`	`id, qty`	`{ ok, … }`	Buys tickets with bank money, up to `MaxTicketsPerBuyer`; each ticket gets a unique `EV-XXXXXX` code
`roadphone:events:cancel`	`id`	`{ ok }`	Cancels an event and marks every ticket for refund
`roadphone:events:end`	`id`	`{ ok }`	Ends an event early
`roadphone:events:sales`	`id`	`{ ok, tickets, sold, revenue, checkedIn, pendingPayout }`	Sales overview for the organizer
`roadphone:events:collect`	—	`{ ok, … }`	Pays out the caller’s pending money
`roadphone:events:members`	—	`{ ok, job, members }`	Active membership cards of the boss’s job (max 300)
`roadphone:events:issueCard`	`playerId, label, color, days`	`{ ok, id, expiresAt }`	Issues a membership card to a nearby player; `days` is `0`, `7`, `30` or `90`
`roadphone:events:revokeCard`	`id`	`{ ok }`	Revokes a card of the boss’s job

roadphone:events:changed (Server → Client) tells the phone to reload the Events app.

Rate limits

Only the phone’s own callbacks are rate-limited; the exports are not.

Action	Limit
Show a card (app)	1 per 2 s per player
Save the ID photo (app)	1 per 3 s per player
Check a ticket in	2 per second per player
Issue a membership card (Business tab)	1 per 2 s per boss

Wallet

Configuration, card types, player flow and troubleshooting

Export Index

Every client and server export of RoadPhone Pro

API documentation

RoadVR

RoadPhone Pro

RoadPhone

RoadPad

RoadCarRadio

Road Minigolf

RoadPark

RoadBanking

Wallet API

Wallet API

Return shape

Reading

getWalletCards

getWalletCard

hasWalletCard

getWalletMemberships

Membership cards

issueWalletCard

revokeWalletCard

Showing and photos

showWalletCard

setWalletPhoto

refreshWallet

Callbacks

Client events

NUI callbacks

Card schema

Global functions (inside the `roadphone` resource)

Events app callbacks

Rate limits

Wallet

Export Index

​Wallet API

​Return shape

​Reading

​getWalletCards

​getWalletCard

​hasWalletCard

​getWalletMemberships

​Membership cards

​issueWalletCard

​revokeWalletCard

​Showing and photos

​showWalletCard

​setWalletPhoto

​refreshWallet

​Callbacks

​Client events

​NUI callbacks

​Card schema

​Global functions (inside the roadphone resource)

​Events app callbacks

​Rate limits

​Related Resources

Wallet

Export Index

Wallet API

Return shape

Reading

getWalletCards

getWalletCard

hasWalletCard

getWalletMemberships

Membership cards

issueWalletCard

revokeWalletCard

Showing and photos

showWalletCard

setWalletPhoto

refreshWallet

Callbacks

Client events

NUI callbacks

Card schema

Global functions (inside the `roadphone` resource)

Events app callbacks

Rate limits

Related Resources