⚙️Configuration

🛠️ Configuration Files

1. Society Configuration (data/society.lua)

This file allows you to set up society accounts with specific permissions and tax rates.

Configuration Structure

{
    accountName = 'society_unique_identifier',
    label = "Display Name",
    job = {'job_name'}, -- Can be string or table of jobs
    grade = minimum_access_grade,
    presetGrade = preset_creation_grade,
    vat = tax_percentage
}

Example Configuration

---@type Society[]
return {
    {
        accountName = 'society_lspd',
        label = "Police",
        job = {'police'},
        grade = 3,     -- Minimum grade to access account
        presetGrade = 4, -- Grade required to create presets
        vat = 5        -- 5% VAT for this society
    },
    {
        accountName = 'society_ambulance',
        label = "Ambulance",
        job = 'ambulance',
        grade = 4,
        presetGrade = 5,
        vat = 5
    }
}

2. General Configuration (data/config.lua)

Configuration Options

return {
    debug = true,              -- Enable debug mode
    personnelVat = 1,           -- Default personal VAT percentage
    openCommand = 'billing',    -- Command to open billing menu
    allowMinus = false          -- Allow negative balances
}

🖥️ State Bag and Functions

Client-Side State Bag

-- Check if player is in billing UI
StateBag: 'billingOpen'

-- Example of listening to state bag changes
AddStateBagChangeHandler('billingOpen', '', function(bagName, key, value)
    -- Handle UI state changes
end)

Server-Side Functions

Pay All Invoices

-- Force pay all player invoices
exports['nfs-billing']:payAll(source)

Send Invoice with customizable details

This export allows you to send an invoice with customizable details.

exports['nfs-billing']:sendInvoice({
    billFrom = 1, -- Sender ID (source, CID, or society ID)
    billTo = 2,   -- Recipient ID (source or CID)
    label = "Parking Fine",
    amount = 250,
    logoUrl = "https://example.com/logo.png",
    discount = 10 -- Discount in percentage or fixed amount
})

Parameters :

• data (object): Contains the invoice details.

  • billFrom (string | number): The sender of the invoice. Accepts a player’s source ID, character ID (CID), or society ID.

  • billTo (string | number): The recipient of the invoice. Accepts a player’s source ID or character ID (CID).

  • label(string): The title or label of the invoice.

  • amount (number): The total amount to be billed.

  • logoUrl (string): The URL of the logo to be displayed in the UI.

  • discount (number): The discount applied to the total amount. This is shown in the UI and calculated in the final price.

Society Financial Management

-- Deposit money to a society account
exports['nfs-billing']:depositSociety(society, amount)

-- Withdraw money from a society account
exports['nfs-billing']:withdrawSociety(society, amount)

-- Get the balance of a society account
exports['nfs-billing']:getSocietyBalance(society)

Registering a Billing Society

Use this export to register a job-based society for billing support, with full control over permissions, commissions, and VAT:

---@type {accountName: string, label: string, job: string, grade: number, withdrawGrade: number, presetGrade: number, societyBalanceGrade: number, playerCommission: number, vat: number}
exports['nfs-billing']:registerSociety({
    accountName = 'society_lspd',     -- Shared account name
    label = 'Police',                 -- Society label
    job = 'police',                   -- Job name
    grade = 3,                        -- Minimum grade to send invoices
    withdrawGrade = 4,                -- Minimum grade to withdraw money
    presetGrade = 4,                  -- Minimum grade to use preset amounts
    societyBalanceGrade = 4,         -- Minimum grade to view society balance
    playerCommission = 5,            -- % commission the player earns per invoice
    vat = 5                           -- % VAT added to invoices
})

🔧 Configuration Tips

Society Configuration

• Ensure accountName is unique

• job can be a single job or multiple jobs

• grade controls access levels

• vat sets tax percentage

General Configuration

• Enable debug for development

• Customize openCommand to fit your server

• allowMinus controls negative balance permissions

🚨 Important Notes

• All societies must be defined in data/society.lua

• Verify job names match your framework

• Test configurations in a controlled environment