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']:AddCustomAppwithidentifier = Config.AppIdentifier(defaultfx-billing), the name, description, developer,defaultApp, category, size, price, a screenshot,uiandicon. - It registers again on
fx-phone:client:phoneLoaded, so an FX Phone restart is covered. - Notifications go through
exports['fx-phone']:SendNotificationon the server, and payments are written to the phone's bank history withAddTransactionwhenConfig.Phone.BankHistory = true. - FX Phone's own Invoices app leaves the home screen while
fx-billingappis 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',
})
senderis a job name or the issuer's citizen id.recipientis a citizen id, or a job name to bill a company.- The permission check is not skipped:
sourcemust be in the job named insenderand on duty. payments_numis the number of installments.payments_periodis days between installments (0,1,7,14,30,90); other values are mapped to the nearest known period.recurring_interval_daysabove0re-issues the invoice after full payment.- The distance and summary rules apply only when
Config.EnforceNearbyOnExports/Config.EnforceSummaryOnExportsare on. VAT is added only whenConfig.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 = 0the 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 = 0the 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' })
vieweris a job name or a citizen id.statusispending,completed,cancelled,scheduledordisputed.- Pass
result.nextCursorback asparams.lastIdfor 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, 0whenConfig.Enforcement.Enabledis off or the database is not ready. - Only invoices older than
Config.Enforcement.GraceMinutescount. Invoices with the same sender and amount insideDuplicateWindowSecondscount 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 |