Configuration

Page dedicated to how to configure our Billing System

Languages

You can set the language of the script in the configuration file.

• en: English

• fr: French

• pl: Polish

• de: German

• es: Spanish

Exports (Server-side)

Category	Export Name	Description
Creation	CreateInvoice	Create an invoice from one player to another
Creation	CreateInvoiceForSociety	Create an invoice addressed to a company/society
Data Retrieval	GetPlayerInvoices	Retrieve all invoices related to a player
Data Retrieval	GetInvoiceById	Fetch a single invoice by ID
Data Retrieval	GetUnpaidInvoicesCount	Count unpaid invoices for a player
Data Retrieval	HasUnpaidInvoices	Quick boolean check for unpaid invoices
Data Retrieval	GetSocietiesList	Get all registered societies
Management	ForcePayInvoice	Force the payment of an invoice (admin only)
Management	CancelInvoice	Cancel an invoice (admin only)
Statistics	GetPlayerStatistics	Get billing statistics for a player
Analytics	AddIncomeToChart	Add an income entry to the analytics chart

1. CreateInvoice

Description: Creates a new invoice from one player to another.

Parameters:

Name	Type	Required	Description
sourcePlayer	number	yes	ID of the player creating the invoice
targetPlayer	number	yes	ID of the player receiving the invoice
items	table	yes	Table of billed items { label, price, quantity }
invoiceType	string	yes	Type of invoice (personal or society)

Returns: boolean — true if successfully created.

Example:

exports.qfbilling:CreateInvoice(
    source, 
    targetId, 
    {
        { label = 'Traffic Violation', price = 500, quantity = 1 },
        { label = 'Parking Fee', price = 200, quantity = 1 }
    },
    'personal'
)

2. CreateInvoiceForSociety

Description: Creates an invoice addressed to a company or registered society.

Parameters:

Name	Type	Required	Description
sourcePlayer	number	yes	ID of the player issuing the invoice
targetSociety	string	yes	Target society name (e.g. police, ambulance)
items	table	yes	Items list { label, price, quantity }
invoiceType	string	no	Defaults to society

Example:

exports.qfbilling:CreateInvoiceForSociety(
    source,
    'mechanic',
    {
        { label = 'Vehicle Service', price = 5000, quantity = 1 },
        { label = 'Spare Parts', price = 1200, quantity = 2 }
    }
)

3. GetPlayerInvoices

Description: Retrieves all invoices belonging to a player (personal, society, and sent).

Parameters:

Name	Type	Required	Description
source	number	yes	Player ID
callback	function	yes	Called with invoices table and money balance

Example:

exports.qfbilling:GetPlayerInvoices(source, function(invoices, money)
    print("Wallet: " .. money)
    print("Personal invoices: " .. #invoices.personal)
    print("Society invoices: " .. #invoices.society)
end)

4. GetInvoiceById

Description: Fetches all details of a specific invoice by its unique ID.

Callback Result Example:

{
  id = 42,
  sendername = "John Doe",
  sendersociety = "police",
  targetname = "Jane Roe",
  amount = 1500,
  items = { { label = "Fine", price = 1500, quantity = 1 } },
  status = "unpaid"
}

Example:

exports.qfbilling:GetInvoiceById(42, function(invoice)
    if invoice then
        print("Invoice ID:", invoice.id)
        print("Total:", invoice.amount)
        print("Status:", invoice.status)
    end
end)

5. GetUnpaidInvoicesCount

Description: Gets the count of unpaid invoices for a player along with summary data.

Example:

exports.qfbilling:GetUnpaidInvoicesCount(source, function(count, data)
    if count > 0 then
        print("You have " .. count .. " unpaid invoices.")
    end
end)

6. HasUnpaidInvoices

Description: Lightweight boolean check to quickly verify if a player has outstanding invoices.

Example:

exports.qfbilling:HasUnpaidInvoices(source, function(hasUnpaid)
    if hasUnpaid then
        print("Player cannot proceed - unpaid invoices detected.")
    else
        print("No outstanding debt.")
    end
end)

7. GetSocietiesList

Description: Retrieves all available societies from the database.

Callback Example:

exports.qfbilling:GetSocietiesList(source, function(societies)
    for _, society in ipairs(societies) do
        print(society.label .. " (" .. society.name .. ")")
    end
end)

8. ForcePayInvoice (Admin Only)

Description: Allows administrators to enforce payment of any invoice.

Example:

exports.qfbilling:ForcePayInvoice(invoiceId, playerId, function(success, message)
    print(message)
end)

9. CancelInvoice (Admin Only)

Description: Cancels a given invoice (admin privilege required).

Example:

exports.qfbilling:CancelInvoice(invoiceId, function(success)
    if success then
        print("Invoice has been successfully cancelled.")
    end
end)

10. GetPlayerStatistics

Description: Returns detailed billing statistics (daily, weekly, monthly).

Example:

exports.qfbilling:GetPlayerStatistics(source, function(data)
    print("Invoices Today: " .. data.personal.stats.totalInvoices.today)
    print("Monthly Income: " .. data.personal.stats.totalIncome.month)
end)

11. AddIncomeToChart

Description: Adds income data to analytics. This function updates the internal income chart.

Example:

exports.qfbilling:AddIncomeToChart("char1123456", "mechanic", 5000)

Data Structures

Data Type	Description
invoiceType	personal, society
invoiceStatus	unpaid, paid, request, rejected, canceled
item	{ label, price, quantity }

Other

1. Framework Detection

Detect which framework your server is running to enable integration automatically.

Config.Frameworks = {
    ESX = { enabled = GetResourceState('es_extended') == 'started' },
    QBCore = { enabled = GetResourceState('qb-core') == 'started' },
    QBox = { enabled = GetResourceState('qbx-core') == 'started' },
    VRP = { enabled = false },
}

Explanation:

• The script checks for the presence of common frameworks (es_extended, qb-core, etc.) and enables relevant functionality.

• You don’t have to manually toggle these unless you use a less common framework.

---

2. Society Names Mapping

Define friendly display names for your in-game jobs/societies.

Config.Societies = {
    ["police"] = "LSPD",
    ["ambulance"] = "EMS",
    ["mechanic"] = "Benny's Garage",
    ["taxi"] = "Downtown Cab Co.",
    -- Add others as needed
}

Usage: The script uses these names in invoices and UI elements. Make sure keys match your job names.

---

3. Invoice Amount Limits

Control the invoice value range.

Config.MinimumInvoiceAmount = 1
Config.MaximumInvoiceAmount = 999999

Example:

• Prevent invoices smaller than 1 unit or larger than 999,999 units.

• Set these based on your server economy scale.

---

4. Invoice Cancellation

Allow users to cancel invoices (both sent and received).

Config.AllowCancelInvoices = true
Config.AllowCancelReceivedInvoices = true

Example:

• Enabling these lets players cancel invoices they created or those sent to them, preventing disputes.

---

5. Proximity Check for Invoice Creation

Ensure realism by only allowing invoicing nearby players.

Config.RequireNearbyTarget = 0      -- 0 = disabled
Config.MaxDistanceForNearbyPlayers = 5.0  -- meters

Example:

• If enabled (>0), the biller must be within 5 meters to create an invoice.

• Helps prevent abuse and adds immersion.

---

6. Job and Grade Restrictions

Restrict who can create or pay society invoices.

Config.EnableGradeRestriction = true
Config.MinimumGradeLevel = 2
Config.SocietyGradePermissions = {
    viewAndCreate = 0,
    pay = 0,
    analytics = 4,
    viewSentInvoices = 0,
}

Explanation:

• Setting viewAndCreate to 0 means all grades in the job can invoice.

• Increasing numbers require higher job ranks (grades) for specific permissions.

• analytics = 4 means only higher ranked members can see financial charts.

---

7. Notification Settings

Control how players get informed about billing events.

Config.ShowNotifications = true
Config.NotificationSystem = "nui"
Config.NotificationDuration = 5000  -- milliseconds
Config.NotificationColors = {
    success = "#4CAF50",
    error = "#f44336",
    info = "#2196F3",
    warning = "#ff9800",
}

Example:

• Players receive colorful pop-up messages for invoice payments, errors, etc.

• Notification colors are customizable per message type.

---

8. Discord Logging Configuration

Send billing events to Discord for audit/logging.

Config.EnableDiscordLogs = true
Config.DiscordWebhooks = {
    main = "https://discord.com/api/webhooks/your-main-webhook",
    created = "https://discord.com/api/webhooks/created-webhook",
    paid = "https://discord.com/api/webhooks/paid-webhook",
}
Config.DiscordColors = {
    created = 3447003,   -- Blue
    paid = 3066993,      -- Green
    canceled = 15158332, -- Red
}

Use case:

• Administrator can monitor billing events remotely.

• Set different webhooks for detailed logs (invoice created, paid, canceled).

---

9. Sound and Hotkey Settings

Enhance user experience with sounds and quick access.

Config.EnableSounds = true
Config.PlaySoundOnCreate = true
Config.PlaySoundOnPay = true
Config.EnableKeybind = true
Config.DefaultKey = "F7"

Example:

• Plays audio feedback on invoice creation and payment.

• Pressing F7 opens billing UI instantly.