Configuration

The config is split into five open files in config/:

File	What it holds
`main.lua`	Language, pages on or off, IBAN, cash, cards and PIN, society, gang and shared accounts, scheduled transfers, `/givecash`, bank robberies
`locations.lua`	Banks, bankers, voices and dialogue, ATMs, target, sounds, HUD
`economy.lua`	Costs, transfer fee, largest amount, savings, loans, Discord webhook
`billing.lua`	Bills
`compat.lua`	Scripts written for other banks, and the account import

In the files each key is written C.Name (for example C.Locale = 'en'). This page writes them Config.Name. Amounts are whole numbers.

Your server, your rules. The five files of config/, locales/ and the inventory images are not encrypted: language and currency, IBAN format, cards and PIN, fees and prices, savings, loans and credit score, bills, society, gang and shared accounts, banks and their bankers, voices, blips, ATM models, target or prompt, sounds, commands and compatibility are all yours to change. With hz_lib, 48 of these settings also change in game from /hzpanel, with no restart.

General

Key	Default	Description
`Config.Locale`	`'en'`	Language of the app, the dialogue and the messages: a file name from `locales/`. `en` and `fr` ship. `nil` uses the `hz_locale` convar.
`Config.Currency`	`'$'`	Currency sign shown in the app.
`Config.Features`	`savings`, `bills`, `loans` all `true`	Turns the Savings, Bills and Loans pages on or off. Off: the page leaves the menu and the server refuses its operations. Nothing is deleted.
`Config.RateLimits`	see file	Most calls per player in a few seconds, for reads, money operations, PIN checks and `/givecash`.
`Config.Debug`	`false`	Extra logs in the console.

Another language: copy locales/en.json to a new file (for example locales/de.json), translate the text, and set Config.Locale = 'de'. No rebuild needed; missing lines fall back to English. The bankers' voices exist in English and French only.

IBAN

Key	Default	Description
`Config.IbanPrefix`	`'NT'`	Prefix of every IBAN, in capitals. A personal IBAN looks like `NT482913`.
`Config.IbanDigits`	`6`	Digits of a generated personal IBAN.
`Config.CustomIbanMaxChars`	`12`	Longest custom IBAN a player can buy, prefix included.

Society accounts get the prefix and the job name (NTPOLICE), gang accounts the prefix, GANG and the gang name (NTGANGBALLAS). Players can't take these as custom IBANs.

Cash

Key	Default	Description
`Config.UseCashAsItem`	`'auto'`	`'auto'`: the cash item with ox_inventory, the framework's cash otherwise. `true` forces the item, `false` the framework's cash.
`Config.CashItem`	`'money'`	Name of the cash item (ox_inventory `money`, qb `cash`).
`Config.BankAccount`	`'bank'`	Framework account used as the personal bank.

Cards & PIN

Key	Default	Description
`Config.RequireCreditCardForATM`	`true`	A bank card is needed to use an ATM. `false`: the PIN alone.
`Config.CreditCardItem`	`'bank_card'`	Item name of the card. It must exist in your inventory, see Installation.
`Config.FirstCardFree`	`true`	A character who never had a card gets the first one free, at the counter or straight at the ATM.
`Config.CardValidityDays`	`90`	Days a new card stays valid. `0` = cards never expire.
`Config.MaxCardsPerAccount`	`3`	Cards a character can hold at once, expired ones not counted. `0` = no limit.
`Config.PinDigits`	`4`	Length of the PIN.
`Config.PinMaxAttempts`	`3`	Wrong PINs in a row before the card is locked.
`Config.PinLockoutSeconds`	`300`	How long the card stays locked.
`Config.PinAtBank`	`false`	Keep `false`: the PIN is asked at ATMs only.

Society & gang accounts

Key	Default	Description
`Config.SocietyAllJobs`	`true`	Every job has a society account, created on first use. `false`: only the jobs of `Config.Societies`.
`Config.Societies`	`police`, `ambulance`, `mechanic`, `realestate`	Jobs whose account is created at start.
`Config.SocietyExcludedJobs`	`unemployed`	Jobs that never have an account.
`Config.SocietyMinGrade`	`3`	Besides the boss, the job grade (and above) that opens the society account. `false` = boss only.
`Config.SocietyMinGradeByJob`	`{}`	Grade per job, for example `{ police = 4 }`.
`Config.BankAuth`	`true`	Qbox: the bank access setting of each grade (in qbx_management) decides who opens society and gang accounts. `false` = the grade rules above.
`Config.EsxSocietyAccounts`	`true`	ESX: society balances are the `society_<job>` accounts of esx_addonaccount, so boss menus and bills see the same money.
`Config.BossGrade`	`nil`	ESX: grade level of the boss (and above). `nil` = the boss flag or a grade named `boss`.
`Config.GangMinGrade`	`false`	Besides the gang boss, the gang grade (and above) that opens the gang account. `false` = boss only.
`Config.GangMinGradeByGang`	`{}`	Grade per gang, for example `{ ballas = 3 }`.
`Config.GangPermissionExport`	`hz_illegal`, `CanAccessGangBank`	Optional export that decides gang access, used only while its resource runs. `false` = none.

Shared accounts

Key	Default	Description
`Config.SharedAccounts`	`true`	Players open shared accounts at a bank counter.
`Config.SharedMaxOwned`	`2`	Shared accounts one character may own.
`Config.SharedMaxMembers`	`5`	Members per shared account, owner not counted.
`Config.SharedNameMax`	`32`	Longest account name.

Scheduled transfers

Key	Default	Description
`Config.MaxScheduledPerAccount`	`10`	Active or paused scheduled transfers per account. `0` = no limit.
`Config.ScheduleMaxRunsShared`	`52`	Most runs of a society or gang scheduled transfer. Those always need a number of runs.

Giving cash

Key	Default	Description
`Config.GiveCash`	`true`	Players hand cash with `/givecash [id] <amount>`; without an ID it goes to the nearest player. `false`: the command isn't created.
`Config.GiveCashCommand`	`'givecash'`	Command name.
`Config.GiveCashDistance`	`3.0`	Most metres between the two players.
`Config.GiveCashMaxAmount`	`0`	Largest gift. `0` = `Config.MaxAmount`.

Bank robberies

Key	Default	Description
`Config.BankClosure`	`true`	A bank closes while it is being robbed.
`Config.BankClosureMinutes`	`30`	It reopens after this delay at the latest. `0` = only when the robbery ends.
`Config.RobberyBanks`	qb-bankrobbery order	Bank id of the robbery script → bank number in `Config.Banks`.

See Closed during a robbery.

Banks

C.Banks = {
    { -- Legion Square
        coords = vec3(150.27, -1040.20, 29.37), brand = 'fleeca',
        ped = { model = 'a_m_m_business_01', coords = vec4(149.38, -1042.05, 29.37, 334.49), name = 'Martin Kessler' },
    },
    -- ...
}

Field	Description
`coords`	Where the player stands in front of the banker. The server measures players from this point.
`brand`	Look of the app: `'fleeca'`, `'maze'`, `'pacific'`, `'blaine'` or `'union'`.
`ped`	The banker: `model`, `coords` (`vec4` with heading) and `name`, shown in the dialogue.
`blip`	Optional: changes any field of `Config.Blip` for this bank, or `false` for no blip.
`distance`	Optional: prompt distance of this bank.

Key	Default	Description
`Config.InteractDistance`	`3.0`	Distance at which a counter's prompt becomes active.
`Config.InteractKey`	`'E'`	Key shown in the prompt (label only).
`Config.Blip`	sprite `108`, colour `2`, scale `0.9`, label `Bank`	Blip of each bank. `enabled = false` hides them.
`Config.BlipColorByBrand`	Maze `1`, Fleeca `2`, Pacific `46`, Blaine `76`, Union `29`	Blip colour of each bank brand.
`Config.BankPedModel`	`'a_m_m_business_01'`	Banker model when a bank sets none.
`Config.BankPedDistance`	`60.0`	Metres at which bankers appear.
`Config.SessionIdleTimeout`	`900`	Seconds without any action before the app closes.

Bankers & dialogue

Key	Default	Description
`Config.StaffVoice.enabled`	`true`	Bankers speak.
`Config.StaffVoice.language`	`'en'`	`'en'`, `'fr'`, or `'auto'` (the language of `Config.Locale`).
`Config.StaffVoice.greetDistance`	`5.0`	Metres at which the banker greets the player.
`Config.StaffVoice.greetCooldown`	`300`	Seconds before the same banker greets the same player again.
`Config.StaffVoice.lookDistance`	`6.0`	Metres at which the banker follows the player with their eyes.
`Config.Dialogue.enabled`	`true`	Talking to a banker opens the dialogue box. `false`: the bank app opens at once.
`Config.Dialogue.camera`	`true`	The camera frames the banker while the dialogue is open.

ATMs

Key	Default	Description
`Config.AtmModels`	`prop_atm_01`, `prop_atm_02`, `prop_atm_03`, `prop_fleeca_atm`	ATM models. Every prop of these models on the map is an ATM.
`Config.AtmDistance`	`1.5`	Metres from an ATM to get its prompt.
`Config.AtmUse.walk`	`true`	The player walks up to the ATM. `false`: they stay in place.
`Config.AtmUse.card`	`true`	Game ATMs: the player inserts their card before the screen opens.
`Config.AtmUse.view`	`'screen'`	Game ATMs: `'screen'` faces the screen and keypad, `'shoulder'` looks over the player's shoulder.
`Config.AtmUse.finger`	`true`	The player's hand on the keypad, the finger on the key under the cursor.
`Config.AtmUse.cardModel`	`false`	One card prop for everyone. `false` = the card of the player's own bank.
`Config.AtmUse.animTime`	`2.0`	ATM models you add: seconds of card animation before the screen opens. `0` = none.
`Config.AtmPositions`	empty	Optional list of allowed ATM positions (`vec3`). Empty = every ATM of the models above.
`Config.AtmPositionTolerance`	`1.5`	Metres between an ATM and its listed position.
`Config.AtmBrand`	`'fleeca'`	Bank of the ATMs: look of the full-screen ATM (models you add) and bank of a first free card handed out there.
`Config.AtmBrandByModel`	`prop_fleeca_atm = 'fleeca'`	The same, per model.

Target, sounds & HUD

Key	Default	Description
`Config.Target.bank`	`true`	Target eye on bankers and their counter (ox_target or qb-target, through hz_lib).
`Config.Target.atm`	`true`	Target eye on ATMs.
`Config.Target.distance`	`2.0`	Reach of the eye, in metres.
`Config.Target.pins`	`true`	With HZ-TextUi running: its pins (shown when near, no key held) instead of the eye.
`Config.Sounds`	game sounds	Sounds of the app: open, close, PIN right and wrong, success, error, keypad, hover, click, page change. `enabled = false` mutes all of them; set one entry to `false` to mute it.
`Config.HideHud`	`true`	Hides the HUD while the app is open (HZ-Hud, or the game's minimap).

Without a target resource, hz_lib shows its own [E] prompt.

Costs & limits

Key	Default	Description
`Config.IbanChangeCost`	`5000`	Price of a custom IBAN.
`Config.PinChangeCost`	`1000`	Price of a PIN change. The first PIN is free.
`Config.CreditCardPrice`	`250`	Price of a bank card.
`Config.TransferFeePct`	`0.0`	Fee on transfers, as a fraction (`0.01` = 1 %), kept by the bank.
`Config.MaxAmount`	`100000000`	Largest amount of a single operation.

Costs are taken from the personal bank.

Savings

C.Savings = {
    InterestPct = 0.5,
    PeriodHours = 24,
    MaxBalance  = 1000000,
    MaxCatchUp  = 7,
}

Key	Description
`InterestPct`	Interest per period, in % of the balance kept for the whole period.
`PeriodHours`	Real hours between two interest payments.
`MaxBalance`	Most a character may keep in savings. `0` = no limit.
`MaxCatchUp`	Periods paid at most after time away. `0` = no limit.

How it works: Savings & loans.

Loans

C.Loans = {
    Tiers = {
        { score = 300, max = 5000,   rate = 15 },
        { score = 580, max = 25000,  rate = 10 },
        { score = 670, max = 75000,  rate = 7 },
        { score = 740, max = 200000, rate = 5 },
    },
    MinAmount    = 1000,
    Installments = { 4, 8, 12 },
    PeriodHours  = 24,
    LateFeePct   = 5,
    DefaultAfter = 3,
    UseSavings   = true,
    Score = { start = 600, min = 300, max = 850, onTime = 5, repaid = 25, missed = 30, default = 100 },
}

Key	Description
`Tiers`	From this credit score: largest loan and its interest, in % of the amount for the whole loan.
`MinAmount`	Smallest loan.
`Installments`	Repayment plans offered, in number of payments.
`PeriodHours`	Real hours between two payments.
`LateFeePct`	Added to the debt for each missed payment, in % of one payment.
`DefaultAfter`	Missed payments in a row before the loan is in default.
`UseSavings`	A payment the bank account can't cover is taken from savings.
`Score`	Starting score, bounds, and points won or lost: on-time payment, loan repaid, missed payment, default.

How it works: Savings & loans.

Bills

All in config/billing.lua, under C.Billing.

Key	Default	Description
`Command`	`'invoice'`	Chat command that writes a bill. `''` = no command.
`Jobs`	`nil`	Jobs that may bill, for example `{ 'police', 'mechanic' }`. `nil` = every job that has a society account.
`MinGrade`	`0`	Lowest job grade allowed to bill.
`MinGradeByJob`	`{}`	Grade per job, for example `{ mechanic = 1 }`.
`Gangs`	`true`	Gang members may bill for their gang.
`PlayerInvoices`	`false`	Players may bill other players, to their own account.
`NoDecline`	`police`, `ambulance`	Jobs whose bills can't be declined (fines).
`MaxAmount`	`1000000`	Largest bill.
`MaxPending`	`20`	Unpaid bills a player may have at once.
`Distance`	`5.0`	Most metres between the writer and the player billed.
`DueDays`	`7`	Real days before a bill is overdue.
`LateFeePct`	`10`	Added once when overdue, in % of the amount. `0` = none.
`AutoCollect`	`true`	Overdue bills are taken from the bank as soon as it covers them.
`IssuerCommission`	`0`	% of a society bill paid to the employee who wrote it.
`ReasonMax`	`96`	Characters kept from the reason.
`PhoneBrand`	`'maze'`	Bank look of the phone Bills app.
`Phones`	`qs-smartphone`, `lb-phone`, `hz_phone`	Phones that get the Bills app and bill notifications, when they run.

How it works: Bills.

Compatibility

In config/compat.lua:

Key	Default	Description
`Config.Compat['qb-banking']`	`true`	Answer the exports of qb-banking. `false` = off.
`Config.Compat['Renewed-Banking']`	`true`	Same for Renewed-Banking.
`Config.Compat['esx_banking']`	`true`	Same for esx_banking.
`Config.Compat['okokBanking']`	`true`	Same for okokBanking.
`Config.Compat['esx_billing']`	`true`	Bills sent by ESX job menus become HZ-Banking bills.
`Config.Compat['qb-management']`	`'auto'`	Old money exports of qb-management, only while no qb-management runs.
`Config.Compat.esxClientLog`	`false`	Let players write lines in their own history through the esx_banking client event.
`Config.MigrationPriority`	`okok`, `renewed`, `qb`, `esx`	Import sources, from most to least trusted.
`Config.MigrationHistory`	`true`	Also import the history lines.

Each relay stays off while the real resource of that name runs. More in Replacing your banking script.

In /hzpanel

The Banking module of /hzpanel edits most settings live on the server, in two tabs:

General — IBAN prefix; Savings, Bills and Loans pages; card and PIN rules, cash mode, society and gang grades, Qbox bank access, ESX society money; shared accounts; /givecash and bank closure.
Economy — IBAN, PIN and card prices, transfer fee (in %), largest amount, scheduled transfer limits; savings; loans; bills (largest invoice, days before overdue, late fee, collecting overdue bills, employee commission, lowest grade that bills, gangs and players billing, billing distance).

48 settings in all, applied at once with no restart. The files give the starting values. A value saved in the panel wins over the file. Banks, ATMs, voices, sounds, loan tiers, the credit score, the bill command and the jobs that bill, and compatibility are set in the files only.

Convars

Convar	Description
`hz_banking_webhook`	Discord webhook URL for the money log.
`hz_banking_pin_secret`	Private secret used to store PINs. Set it once, before players set their PINs.

See Installation.