> For the complete documentation index, see [llms.txt](https://needforscript.gitbook.io/needforscripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://needforscript.gitbook.io/needforscripts/our-scripts/billing-script/configuration.md).

# 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

```lua
{
    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

```lua
---@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

```lua
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

{% hint style="success" %}

#### Client-Side State Bag

{% endhint %}

```lua
-- 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)
```

{% hint style="success" %}

#### Server-Side Functions

{% endhint %}

### Pay All Invoices

```lua
-- 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.

```lua
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

```lua
-- 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:

```lua
---@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