Configuration

Complete configuration reference for nc-banking V2.
All settings live in config/config.lua inside the resource.

Locale & Currency

-- Language
a--@type 'en' | 'de' | 'fr' | 'es' | 'pt'
Config.Locale = 'en'

-- Currency display
Config.CurrencySymbol   = '$'
Config.CurrencyPosition = 'before'   -- 'before' → $1,000  |  'after' → 1,000$
Config.CurrencyLocale   = 'en-US'    -- JS locale for formatting (e.g. 'de-DE', 'fr-FR', 'ko-KR')
Config.CurrencyDecimals = 0          -- 0 = $1,000  | 2 = $1,000.00

• Locale controls all server messages, dialogs, and NUI text.
• Currency options are display-only; they do not change stored values, only how
  money appears in the UI.

Framework & Target

---@type 'qbcore' | 'qbox' | 'esx' | 'ox' | 'auto'
Config.Framework = 'auto'

-- OX Core: minimum group grade to be considered boss
Config.OxBossGrade = 3

---@type 'auto' | 'ox_target' | 'qb-target' | 'qtarget' | 'interact'
Config.TargetSystem = 'auto'

• Framework = 'auto' detects QBCore / QBox / ESX / OX Core automatically.
• TargetSystem:
  • 'ox_target', 'qb-target', 'qtarget' → use that target resource.
  • 'interact' → E-key prompts only, no target resource.
  • 'auto' → prefer ox_target > qb-target > qtarget > interact.

Inventory System

---@type 'auto' | string
Config.InventorySystem = 'auto'    -- 'auto' or specific inventory resource name

Config.InventoryPresets = {
    {
        resource = 'ox_inventory',
        hasItem  = 'GetItemCount',
        addItem  = 'AddItem',
        removeItem = 'RemoveItem',
        getCount = 'GetItemCount',
        metadataFormat = 'direct',  -- AddItem(source, item, amount, metadata)
    },
    {
        resource = 'qb-inventory',
        hasItem  = 'HasItem',
        addItem  = 'AddItem',
        removeItem = 'RemoveItem',
        getCount = 'GetItemCount',
        metadataFormat = 'slot',    -- AddItem(source, item, amount, nil, metadata)
    },
    -- qs-inventory, ps-inventory, codem-inventory, core_inventory...
}

• InventorySystem = 'auto' → first matching preset in InventoryPresets wins.
• To support a custom inventory, just add a new entry to InventoryPresets.
• metadataFormat controls how metadata is passed to the AddItem export.

E Key Interaction

Used when no target system is available (or when TargetSystem = 'interact').

Config.InteractKey = 38            -- E key
Config.InteractPrompt = '[E]'
Config.InteractDrawDistance = 10.0
Config.InteractFontScale = 0.35
Config.InteractDistance = 2.5

Database

Config.AutoInstallSQL = true

• When true, nc-banking will:
  • Create all required tables on first start.
  • Run upgrade queries when needed (e.g. add new columns).
• Set to false if you prefer to manage sql/install.sql manually.

NPC Exclusivity

Config.NPCExclusive = true      -- Only one player can use an NPC at a time
Config.NPCLockTimeout = 300     -- Seconds before lock auto-expires

Prevents two players from using the same teller NPC simultaneously.

Force Close Other NUI & External UI Toggle

Config.ForceCloseOtherNUI = false

Config.CloseResources = {
    -- { resource = 'ox_inventory', export = 'closeInventory' },
    -- { resource = 'qb-inventory', event  = 'qb-inventory:client:closeinv' },
}

Config.ExternalUIToggle = {
    -- { resource = 'nox-name', export = 'ToggleNameplate' },
    -- { resource = 'nc-hud',   export = 'ToggleHUD' },
    -- { resource = 'nox-chat', showEvent = 'nox-chat:setVisibleBySetting', showArg = true,
    --                          hideEvent = 'nox-chat:setVisibleBySetting', hideArg = false },
}

• ForceCloseOtherNUI = true → fire close exports/events when banking NUI opens.
• ExternalUIToggle → optional soft toggle (hide HUD/chat while banking UI is open,
  show when closed).

PIN & Security

Config.RequirePin = true
Config.RequirePinOnATM = true
Config.RequirePinOnNPC = false
Config.DefaultPin = '0000'
Config.PinLength = 4
Config.MaxPinAttempts = 5
Config.PinLockoutTime = 30        -- seconds
Config.ForgotPinFee = 500         -- fee for PIN reset at NPC (0 = free)

• Use PIN on ATM only, NPC only, or both.
• Lockout and reset fee help prevent brute-force PIN attempts.

Transactions & ATM Fees

Config.MoneyCountVolume    = 0.6
Config.MoneyCountEndVolume = 0.7

Config.TransactionLogLimit = 50
Config.TransferFee = 0.0           -- 0.0 = no fee, 0.05 = 5%

Config.ATMFees = {
    withdraw = 50,                 -- Flat fee on ATM withdrawals (0 = no fee)
    deposit  = 50,                 -- Flat fee on ATM deposits (0 = no fee)
}

Config.MinTransferAmount = 1
Config.MaxTransferAmount = 1000000

• ATMFees apply only to ATM operations (not NPC teller operations).
• Fees are logged and shown in ATM confirmations / history.

Transfer Security

Config.TransferCooldown = 5                -- seconds between transfers per player
Config.OfflineTransferMainAccount = false  -- allow to offline main account (risky)
Config.OfflineTransferSubAccount = true    -- allow to offline sub-accounts
Config.MaxAccountLookupFails = 5           -- failed account lookups before block
Config.AccountLookupBlockDuration = 60     -- seconds of block

Prevents brute-force account number guessing and spam transfers.

Account Number System & Business Auto-Create

Config.BankName = 'NC'              -- account prefix, e.g. NC-000000000001
Config.AccountNumberLength = 12
Config.SelfTransferFee = false

Config.BusinessAutoCreate = true

Config.AutoBusinessJobs = {
    { name = 'mechanic',  label = 'LS Customs' },
    -- { name = 'police',    label = 'Police Department' },
}

• If BusinessAutoCreate is enabled, business accounts are created and updated
  for configured jobs automatically.
• Boss detection uses your framework or Config.OxBossGrade (for OX Core).

Savings, Personal, Business & Shared Accounts

-- Savings
Config.SavingsEnabled = true
Config.SavingsInterestRate = 0.02      -- 2% per interval
Config.SavingsInterestInterval = 60    -- minutes
Config.MaxSavingsAccounts = 3
Config.MaxSavingsBalance = 500000
Config.MinSavingsDeposit = 100
Config.MinSavingsWithdraw = 100
Config.MaxSavingsGoals = 5

-- Personal
Config.PersonalAccountEnabled = true
Config.MaxPersonalAccounts = 3
Config.MaxPersonalBalance = 1000000
Config.MinPersonalDeposit = 1
Config.MinPersonalWithdraw = 1

-- Business
Config.BusinessAccountEnabled = true
Config.MaxBusinessBalance = 10000000
Config.MinBusinessDeposit = 1
Config.MinBusinessWithdraw = 1
Config.BusinessDepositAllMembers = true

-- Shared
Config.SharedAccountEnabled = true
Config.MaxSharedAccounts = 2
Config.MaxSharedMembers = 10
Config.MaxSharedBalance = 5000000
Config.MinSharedDeposit = 1
Config.MinSharedWithdraw = 1
Config.SharedWithdrawOwnerOnly = true

These limits help protect your economy (max balances, minimum operations, etc.).

Loans & Credit Score

-- Loans
Config.LoanEnabled = true
Config.MinLoanAmount = 1000
Config.MaxLoanAmount = 100000
Config.LoanInterestRate = 0.10       -- 10% flat interest
Config.MaxActiveLoans = 2
Config.LoanDurations = { 7, 14, 30 }
Config.LoanMinPayment = 500

-- Auto-pay
Config.LoanAutoPayEnabled = true
Config.LoanAutoPayInterval = 1440    -- minutes
Config.LoanAutoPayPercent = 0.10
Config.LoanAutoPayMinAmount = 500

-- Penalties
Config.LoanGracePeriodHours = 6
Config.LoanLatePenaltyEnabled = true
Config.LoanLatePenaltyType = 'flat'  -- 'flat' or 'percent'
Config.LoanLatePenaltyAmount = 500
Config.LoanBalanceMultiplier = 3     -- Max loan = total balance × multiplier

-- Credit Score
Config.CreditScoreEnabled = true
Config.CreditScoreMinForLoan = 400
Config.CreditScoreRules = {
    baseScore = 350,
    maxScore  = 850,
    minScore  = 300,
    -- see config.lua for detailed rules
}
Config.CreditTiers = {
    { name = 'Poor',      minScore = 300, maxLoan = 5000,   interestMod = 0.05 },
    { name = 'Fair',      minScore = 450, maxLoan = 25000,  interestMod = 0.02 },
    { name = 'Good',      minScore = 550, maxLoan = 50000,  interestMod = 0.00 },
    { name = 'Very Good', minScore = 650, maxLoan = 75000,  interestMod = -0.02 },
    { name = 'Excellent', minScore = 750, maxLoan = 100000, interestMod = -0.03 },
}

Invoices / Billing & Phone App

Config.BillingEnabled = true
Config.InvoiceExpireDays = 7
Config.MaxPendingInvoices = 20
Config.AllowDeclineInvoice = true
Config.AllowPayAllInvoices = true

Config.BillingAppEnabled = true
Config.BillingAppKeybind = 'F6'
Config.BillingAppCommand = 'billing'
Config.BillingAppCanSend = true
Config.BillingAppSendBossOnly = false
Config.BillingAppNotifyOnNew = true

---@type 'standalone' | 'okokPhone' | 'lb-phone' | 'auto'
Config.PhoneIntegration = 'lb-phone'

• BillingAppEnabled controls the standalone billing NUI.
• PhoneIntegration lets you tie billing notifications to your phone resource.

Notification System

---@type 'ox_lib' | 'qb' | 'esx' | 'custom'
Config.NotificationType = 'qb'

• Choose how notifications are displayed.
• Use 'custom' if you want to plug in your own notify wrapper.

NPC Locations & Dialog

Config.BankNPCs = {
    {
        id = 'bank_pacific_1',
        name = 'Bank Teller',
        displayName = 'Bank Teller',
        model = 'u_f_m_casinocash_01',
        coords = vector4(149.57, -1042.11, 29.37, 338.29),
        dialogTitle = 'Bank Teller',
        dialogSubtitle = 'Pacific Standard Branch',
        greeting = 'Welcome to Pacific Standard Public Deposit Bank! How may I assist you today?',
        blip = { enabled = true, sprite = 108, color = 2, scale = 0.9, label = 'Pacific Standard Bank' },
    },
    -- more NPCs ...
}

Each NPC config controls:

• Ped model, location, and heading.
• Dialog title/subtitle and greeting line.
• Map blip visibility, sprite, color, and scale.

NPC interaction menu options:

Config.BankDialogOptions = {
    {
        label = 'My Account',
        type = 'category',
        description = 'Balance, deposit, withdraw, PIN',
        npcResponse = 'Of course! What would you like to do with your account?',
        children = {
            { label = 'Check Balance',        type = 'clientEvent', clientEvent = 'nc-banking:client:checkBalance' },
            -- ...
        },
    },
    -- Transfers, Loans & Credit, Billing, Card Services, Banking Dashboard, etc.
}

You can add/remove categories or items to customise what the NPC offers.

ATM System

Config.ATMEnabled = true
Config.ATMInteractDistance = 2.0

Camera Presets

Config.ATMCameraPresets = {
    {
        name = 'default',
        distance = 0.8,
        rightOffset = 0.0,
        height = 1.4,
        lookAtHeight = 0.8,
        fov = 42.0,
        transitionMs = 800,
        dof = true,
        dofNear = 0.3,
        dofFar = 4.0,
        dofStrength = 0.6,
        models = { 'prop_atm_01' },
    },
    -- 'fleeca', 'fmshop', etc.
}

ATM Spawner & Calibration

Config.ATMSpawnEnabled = true
Config.ATMSpawnModel = 'prop_atm_01'
Config.ATMSpawnCommand = 'atmspawn'
Config.ATMDeleteCommand = 'atmdelete'

Config.ATMCalibration = {
    enabled = true,
    command = 'atmcalibrate',
    permission = 'ACE',          -- uses Config.AdminAcePermission
    coordsFile = 'atm_coords.json',
    debug = false,
}

ATM Overlay & Keypad

Config.ATMNUI = {
    enabled = true,
    debug = false,
    screen = { left = 38, top = 20, width = 24, height = 55 },
    buttonWidth = 3.5,
    buttonHeight = 3.5,
    buttonGap = 0.8,
    leftButtons = {
        { label = 'Balance',  event = 'checkBalance',  top = 12 },
        { label = 'Deposit',  event = 'deposit',       top = 30 },
        -- ...
    },
    rightButtons = {
        { label = 'PIN',      event = 'pinChange',     top = 12 },
        -- ...
    },
    pinPad = {
        enabled = true,
        left = 35,
        bottom = 0,
        width = 8,
        height = 20,
        keyGap = 6,
    },
}

You can tune the overlay for custom ATM models via ATMCameraPresets and ATMNUI.

ATM dialog (simple menu without 3D overlay):

Config.ATMDialogOptions = {
    { label = 'Check Balance',  type = 'clientEvent', clientEvent = 'nc-banking:client:checkBalance' },
    { label = 'Deposit',        type = 'clientEvent', clientEvent = 'nc-banking:client:deposit' },
    -- ...
}

Bank Card System

Config.BankCard = {
    enabled       = true,
    useInventory  = true,
    itemName      = 'atm_card',
    issueAtNPC    = true,
    requireForATM = true,
    transferable  = true,
    maxCards      = 10,
    reissueFee    = 250,

    -- Card grades & daily limits
    dailyLimitEnabled   = true,
    dailyLimitResetHour = 0,
    defaultGrade        = 'standard',

    grades = {
        standard = { label = 'Standard Card', dailyLimit = 5000,   cost = 0,    order = 1 },
        premium  = { label = 'Premium Card',  dailyLimit = 25000,  cost = 500,  order = 2 },
        gold     = { label = 'Gold Card',     dailyLimit = 100000, cost = 2000, order = 3 },
        platinum = { label = 'Platinum Card', dailyLimit = 0,      cost = 5000, order = 4 },
    },

    messages = {
        issued            = 'Bank card has been issued.',
        noCard            = 'You need a bank card to use the ATM.',
        maxReached        = 'You already have the maximum number of cards.',
        alreadyExists     = 'A card for this account already exists.',
        removed           = 'Your bank card has been removed.',
        dailyLimitReached = 'Daily spending limit reached. Remaining: $%s / $%s',
        upgraded          = 'Card upgraded to %s.',
    },
}

• useInventory = true → real item + DB entry, requires metadata-capable inventory.
• transferable = true → cards can be given to other players and used at ATMs.
• dailyLimitEnabled and grades control per-card daily spending caps.

Banking Job System (Branches, Vaults, Employees)

Config.BankingJob = {
    enabled = true,

    roles = {
        owner   = { label = 'Owner',   level = 3 },
        manager = { label = 'Manager', level = 2 },
        teller  = { label = 'Teller',  level = 1 },
    },

    permissions = {
        teller     = 1,
        cards      = 1,
        transfers  = 1,
        loans      = 2,
        vault      = 2,
        invoices   = 2,
        settings   = 3,
        business   = 3,
        hire       = 2,
        fire       = 2,
    },

    purchase = {
        moneyType = 'bank',   -- 'bank' or 'cash'
    },

    vault = {
        enabled          = true,
        maxBalance       = 5000000,
        startingBalance  = 100000,
        affectATMWithdrawals = false,
        affectNPCWithdrawals = false,
    },

    loanReview = {
        enabled         = false,
        maxInterestAdjust = 0.05,
        autoApproveBelow  = 5000,
    },

    tablet = {
        enabled          = true,
        allowSelfCustomer = true,
    },

    disableNPCAtOwnedBranches = false,

    atmPlacement = {
        enabled   = true,
        maxRadius = 60.0,
    },

    purchaseNpc = 'ig_lifeinvad_01',
    branches = {
        {
            id = 'pacific',
            label = 'Pacific Standard',
            npcPrefix = 'bank_pacific',
            price = 750000,
            purchaseCoords = vector4(146.8, -1043.7, 29.37, 164.46),
            atmRadius = 60.0,
            employeeSpots = {
                vector4(149.20, -1045.20, 29.37, 340.0),
                -- ...
            },
        },
        -- more branches...
    },
}

Key ideas:

• enabled = true turns on branch ownership + banking job.
• roles and permissions define who can use which features.
• vault controls branch vault balances and whether withdrawals affect vaults.
• atmPlacement and branches[*].atmRadius define where owners can place ATMs.

You can disable the entire job/branch system with:

Config.BankingJob.enabled = false

In that case, nc-banking behaves closer to V1 (no branches, no job), while still
using the new UI and ATM features.

Admin Permissions

Config.AdminAcePermission = 'nc-banking.admin'

Grant via server.cfg:

add_ace group.admin nc-banking.admin allow

Used for admin-only commands such as ATM spawn/calibration and certain
banking job management actions.

Discord Webhook Logs

Config.DiscordLogs = {
    enabled     = false,
    botName     = 'NC Banking',
    serverName  = 'My Server',
    avatarUrl   = '',
    dateFormat  = '%Y-%m-%d %H:%M:%S',

    defaultWebhook = '',

    webhooks = {
        deposit  = { enabled = true },
        withdraw = { enabled = true },
        transfer = { enabled = true },
        savings  = { enabled = true },
        loan     = { enabled = true },
        invoice  = { enabled = true },
        card     = { enabled = true },
        account  = { enabled = true },
        admin    = { enabled = true },
    },
}

• Enable and point defaultWebhook (or per-category URLs) to your Discord webhook.
• Each category logs structured embeds (amounts, players, accounts, etc.).