Finance - Payments

Cash management (Wallet), bill creation, fines, and direct charges

The Wallet and Billing components handle player cash operations and billing. Wallet manages on-hand cash, while Billing handles pending bills, government fines, and direct account charges.

Overview

• Wallet - Access via the Wallet component (server-side only)
• Billing - Access via the Billing component (server-side only)

Server-Side Only: All payment operations must be performed on the server. Use Wallet methods instead of directly calling char:SetData('Cash', ...) — the Wallet component handles balance validation and player notifications automatically.

---

Wallet

Wallet:Get

Get a player’s current cash balance.

Wallet:Get(source)

source · number · required

Player server ID

cash · number

Current cash balance (defaults to 0 if no character found)

Example:

local cash = Wallet:Get(source)
print('Player has $' .. cash .. ' cash')

---

Wallet:Has

Check if a player has at least a specified amount of cash.

Wallet:Has(source, amount)

source · number · required

Player server ID

amount · number · required

Amount to check (must be > 0)

hasCash · boolean

true if player’s cash >= amount

Example:

if Wallet:Has(source, 500) then
    -- Player can afford it
else
    Notification:Error(source, 'Not enough cash')
end

---

Wallet:Modify

Add or remove cash from a player’s balance. Handles notifications automatically.

Wallet:Modify(source, amount, skipNotify)

source · number · required

Player server ID

amount · number · required

Amount to add (positive) or remove (negative)

skipNotify · boolean

Skip sending the player a notification (default: false)

newBalance · number|boolean

New cash balance on success, false if insufficient funds or no character found

Examples:

-- Give player $500 cash (shows notification: "You Received $500 In Cash")
Wallet:Modify(source, 500)

-- Remove $200 cash (shows notification: "You Paid $200 In Cash")
local result = Wallet:Modify(source, -200)
if not result then
    -- Player didn't have enough cash
end

-- Give cash silently (no notification)
Wallet:Modify(source, 1000, true)

Cash Transfer Between Players

-- Remove from sender (silent) then add to receiver (silent)
if Wallet:Modify(source, -amount, true) then
    Wallet:Modify(targetSource, amount, true)
else
    -- Sender doesn't have enough cash
end

---

Billing

Billing:Create

Creates a pending bill for a player. The bill appears on their phone and they can accept or dismiss it.

Billing:Create(source, name, amount, description, cb)

source · number · required

Player server ID to bill

name · string · required

Bill title/sender name

amount · number · required

Bill amount in dollars

description · string · required

Bill description

cb · function

Callback when bill is paid or dismissed: function(wasPaid, withAccount)

Example:

-- Hospital bill after treatment
Billing:Create(source, 'Pillbox Medical', 2500, 'Emergency medical treatment', function(wasPaid, withAccount)
    if wasPaid then
        Logger:Info('Billing', 'Medical bill paid', {
            console = true,
            file = true
        }, {
            account = withAccount,
            amount = 2500
        })
    end
end)

---

Billing:Accept

Player accepts and pays a pending bill from a specified account.

Billing:Accept(source, billId, withAccount)

source · number · required

Player server ID

billId · number · required

Bill identifier

withAccount · string

Account number to pay from (defaults to personal account). Requires WITHDRAW permission and sufficient balance.

success · boolean

true if payment was processed

---

Billing:Dismiss

Player dismisses a pending bill without paying.

Billing:Dismiss(source, billId)

source · number · required

Player server ID

billId · number · required

Bill identifier

success · boolean

true if bill was dismissed

---

Billing:Fine

Issues a government fine to a player. The fine amount is split between multiple parties.

Billing:Fine(finingSource, targetSource, amount)

finingSource · number · required

Server ID of the officer issuing the fine

targetSource · number · required

Server ID of the player being fined

amount · number · required

Fine amount in dollars

result · table|boolean

{amount = number, cut = number} on success, false on failure

Fine Revenue Split:

Recipient	Percentage
Fining officer	15%
Police department	25%
State (account 100000)	60%

Example:

local result = Billing:Fine(source, targetSource, 500)

if result then
    Notification:Success(source, 'Fine issued: $' .. result.amount .. ' (Your cut: $' .. result.cut .. ')')
else
    Notification:Error(source, 'Failed to issue fine')
end

---

Billing:Charge

Direct charge against a player’s personal bank account.

Billing:Charge(source, amount, title, description)

source · number · required

Player server ID

amount · number · required

Amount to charge

title · string · required

Charge title

description · string · required

Charge description

result · number|boolean

Charged amount on success, false if insufficient funds

Example:

local result = Billing:Charge(source, 150, 'Mechanic Service', 'Vehicle repair')

if result then
    Notification:Info(source, 'Charged $' .. result)
end

---

Billing:PlayerCreateOrganizationBill

An organization creates a bill for a player. Requires BILL permission on the account.

Billing:PlayerCreateOrganizationBill(billingSource, stateId, account, amount, description)

billingSource · number · required

Server ID of the employee creating the bill

stateId · number · required

Target character State ID

account · string · required

Organization account number

amount · number · required

Bill amount

description · string · required

Bill description

success · boolean

true if bill was created

Example:

-- Mechanic shop billing a customer
local success = Billing:PlayerCreateOrganizationBill(
    source,
    targetChar:GetData('SID'),
    'mechanic_shop',
    3500,
    'Engine rebuild + paint job'
)

---

Next Steps

Finance - Banking

Account management and balances

Finance - Loans

Loan and credit system

Finance - Crypto

Cryptocurrency system

Jobs API

Job management for permissions