Features

Billing (fx-billingapp)

The bundled invoice app, how it installs into the phone, its main settings and its server exports.

#What it is

fx-billingapp is an invoice app. Players and companies send invoices, recipients pay them from the app, and bosses manage their company's billing.

What players get:

  • Home: what they owe, how much is overdue, how much falls due soon, disputes waiting on them, Pay all, and what others owe them.
  • History: received and sent invoices with status, search, date and amount filters, and bulk cancel for sent invoices.
  • New: nearby recipients, the company price list with quantities, VAT shown before sending, installments, payment period, recurring invoices and attachments.
  • Invoice: a receipt with lines, VAT, late fees, installment progress, due time, attachments, the dispute and the full timeline.
  • Business (bosses and managers): collected, waiting, VAT and commission totals, top staff, disputes to settle, the price list, brand colour and logo, and per-grade send and manage rights with commission.
  • Lookup (jobs in Config.Lookup): a citizen's open invoices and debt, read only and logged.

#Requirements

Resource Required Notes
oxmysql Yes Database access
QBCore, Qbox or ESX Yes Detected automatically; server/frameworks/standalone.lua is the adapter for anything else
fx-phone No Without a phone the app opens standalone with a key (default F7)
A company bank Only for company invoices See below

Invoices between players work with every banking script, because personal money goes through the framework. Config.CompanyMoneySystem only affects company (society) accounts. qb-banking, Renewed-Banking, okokBanking, qb-management, esx_addonaccount and tgiann-bank are detected automatically. For any other bank, fill in server/company-money/custom.lua and set Config.CompanyMoneySystem = "custom".

#Installation

cfgensure oxmysql
ensure fx-phone
ensure fx-billingapp

The tables are created on start when Config.CheckDatabase = true (default). If the console reports a schema error, run setup/sql/install.sql by hand. It is safe to run more than once.

A good start prints one line naming the framework, the company money system, the app id and the locale.

#How it registers into the phone

The resource has one adapter file per phone in client/phone/. With Config.Phone.Resource = "auto" it uses FX Phone when FX Phone is running.

  • The FX Phone adapter calls exports['fx-phone']:AddCustomApp with identifier = Config.AppIdentifier (default fx-billing), the name, description, developer, defaultApp, category, size, price, a screenshot, ui and icon.
  • It registers again on fx-phone:client:phoneLoaded, so an FX Phone restart is covered.
  • Notifications go through exports['fx-phone']:SendNotification on the server, and payments are written to the phone's bank history with AddTransaction when Config.Phone.BankHistory = true.
  • FX Phone's own Invoices app leaves the home screen while fx-billingapp is running, so there is one invoice app, not two.

To keep the app from starting at all, set ['fx-billingapp'] = false in Config.BundledApps in FX Phone's configs/config_apps.lua. See Apps.

#Config highlights

config.lua:

Setting Default Meaning
Config.AppIdentifier "fx-billing" App id on the phone
Config.DefaultApp true Installed on every phone
Config.Phone.Resource "auto" Which phone to install into
Config.Phone.BankHistory true Write payments to the phone's bank history
Config.DefaultKeybind "f7" Key for the standalone interface
Config.Framework "auto" Set it when detection picks the wrong framework
Config.CompanyMoneySystem "auto" Set it when detection picks the wrong bank
Config.Locale, Config.Currency Language file and currency symbol
Config.CanIndividualsSend false Players may bill each other personally
Config.EmployedSendAsCompanyOnly true Anyone employed bills only in the company's name
Config.MaxDistance 5.0 How close the recipient must stand
Config.MinSummaryLength 8 Minimum summary length; 0 disables
Config.LogRetentionDays 7 How long the audit trail is kept; 0 keeps it forever
Config.Grades empty Restrict a job's billing to certain ranks
Config.Commission empty Employee cut per job and grade
Config.Enforcement enabled Vehicle lock while invoices are unpaid (GraceMinutes, DuplicateWindowSeconds, NotifyMessage)
Config.Vat off VAT on company invoices, rate per job, optional state account
Config.Disputes on Recipients may dispute an invoice; ExpireHours closes unanswered ones
Config.PayAll true The Pay all button
Config.Lookup Jobs that may look up a citizen's open invoices
Config.Business all on Price list, grade editor and brand settings
Config.EnforceNearbyOnExports, Config.EnforceSummaryOnExports false Apply the distance and summary rules to invoices created through exports
Config.Functions empty functions SentInvoice, PaidInvoice, CancelledInvoice hooks, each called with (source, invoice)

config_server.lua is server only. It holds Config.Webhook (Discord logging: enabled switch, webhook address, server name and an optional bot token), Config.RateLimit and Config.Limits. Put every secret there.

#Server exports

All exports are server side. source = 0 means "run as the server" and skips the permission check where noted.

#SendInvoice

Also available as: CreateInvoice

Creates an invoice in the name of the issuing player.

lua---@param source number  Player who issues the invoice
---@param data table  { sender, recipient, amount, summary, sender_label?, recipient_label?, payments_num?, payments_period?, recurring_interval_days?, attachments? }
---@param callback? fun(ok: boolean, invoice: table|nil, reason: string|nil)
---@return boolean ok
---@return table|string invoiceOrReason
exports['fx-billingapp']:SendInvoice(source, data, callback)
lualocal ok, invoice = exports['fx-billingapp']:SendInvoice(source, {
    sender = 'mechanic', recipient = 'ABC12345', amount = 2500, summary = 'Engine repair and oil change',
})
  • sender is a job name or the issuer's citizen id. recipient is a citizen id, or a job name to bill a company.
  • The permission check is not skipped: source must be in the job named in sender and on duty.
  • payments_num is the number of installments. payments_period is days between installments (0, 1, 7, 14, 30, 90); other values are mapped to the nearest known period.
  • recurring_interval_days above 0 re-issues the invoice after full payment.
  • The distance and summary rules apply only when Config.EnforceNearbyOnExports / Config.EnforceSummaryOnExports are on. VAT is added only when Config.Vat.OnExports = true.
  • Failure reasons: invalidData, noSendPermissions, invalidRecipient, tooFar, invalidAmount, summaryTooShort, summaryInvalid.

#CancelInvoice

Cancels a pending invoice.

lua---@param source number  Player, or 0 to run as the server
---@param data number|table  Invoice id, or { id, actor? }
---@return boolean ok
---@return string|nil reason
exports['fx-billingapp']:CancelInvoice(source, data)
luaexports['fx-billingapp']:CancelInvoice(0, 42)
  • With source = 0 the permission check is skipped and the invoice is cancelled in the name of the account that issued it.
  • Failure reasons: invalidData, notFound, noPermission.

#PayInvoice

Pays an invoice, or its next installment.

lua---@param source number  Player, or 0 to run as the server
---@param data number|table  Invoice id, or { id, payer?, fullAmount? }
---@return boolean ok
---@return table|string resultOrReason  { fullyPaid: boolean } on success
exports['fx-billingapp']:PayInvoice(source, data)
lualocal ok, result = exports['fx-billingapp']:PayInvoice(0, { id = 42, fullAmount = true })
  • With source = 0 the payment is taken from the recipient account and the permission check is skipped.
  • With a real player source the payment is limited to what that player may pay.

#GetInvoices

Returns a page of invoices for a player or a company.

lua---@param source number  Player, or 0 to run as the server
---@param params table  { tab = 'received'|'sent', viewer, status?, query?, lastId? }
---@return table result  { rows: table[], nextCursor: any }
exports['fx-billingapp']:GetInvoices(source, params)
lualocal result = exports['fx-billingapp']:GetInvoices(0, { tab = 'received', viewer = 'mechanic', status = 'pending' })
  • viewer is a job name or a citizen id.
  • status is pending, completed, cancelled, scheduled or disputed.
  • Pass result.nextCursor back as params.lastId for the next page.
  • When the viewer cannot be resolved the result is { rows = {} }.

#GetStats

Returns invoice totals for a player or a company.

lua---@param source number  Player, or 0 to run as the server
---@param viewer string  Job name or citizen id
---@return table|nil stats  stats.totals has owedByMe, owedToMe, totalPaid, totalReceived, penaltiesOwed, pendingCount, sentPendingCount
exports['fx-billingapp']:GetStats(source, viewer)
lualocal stats = exports['fx-billingapp']:GetStats(0, 'mechanic')

Returns nil when the viewer cannot be resolved.

#HasUnpaidInvoices

Tells whether a player has unpaid invoices past the grace period. Used by the garage lock.

lua---@param identifier string  Citizen id
---@param notifyIfBlocked? boolean  Send the player a phone and framework notification when blocked
---@return boolean blocked
---@return number owedTotal
exports['fx-billingapp']:HasUnpaidInvoices(identifier, notifyIfBlocked)
lualocal blocked, owed = exports['fx-billingapp']:HasUnpaidInvoices(citizenid, false)
  • Returns false, 0 when Config.Enforcement.Enabled is off or the database is not ready.
  • Only invoices older than Config.Enforcement.GraceMinutes count. Invoices with the same sender and amount inside DuplicateWindowSeconds count once.

#GetVersionStatus

Returns the result of the update check.

lua---@return table status  { state: string, current: string, latest: string|nil, behind: number|nil }
exports['fx-billingapp']:GetVersionStatus()
lualocal status = exports['fx-billingapp']:GetVersionStatus()

#Optional integrations

setup/integration/garage.lua shows how a garage script blocks vehicles while invoices are unpaid, and setup/integration/exports_example.lua shows the exports above. Both are reference files: copy what you need into your own resource and do not add them to a manifest.

#Troubleshooting

Symptom Cause or fix
App does not appear on the phone The phone must start before this resource. Check the console for an install error
Company invoices cannot be paid The configured bank resource is not running. Player-to-player invoices are unaffected
Recipient list is always empty Config.ShowOnlyNearbyPlayers = true only lists players within Config.MaxDistance metres
"This person is not next to you" Config.EnforceNearbyOnSend re-checks the distance on the server. Raise Config.MaxDistance if needed
No Discord logs Config.Webhook.Enabled must be true and the address filled, in config_server.lua