⚙️Configuration

Configuration for KS-Bank

🌍 General Settings

Basic server settings to integrate the script with your environment.

Variable	Description	Default
Config.Framework	Set your framework ('esx', 'qb', 'qbx') or use 'auto' for automatic detection.	'auto'
Config.TargetSystem	Set your target system ('ox_target', 'qb-target') or use 'auto'.	'auto'
Config.Locale	The language of the script (e.g., 'en', 'it', 'es'). Matches files in locales/.	'en'
Config.Debug	Enables debug prints in the server console for troubleshooting.	false
Config.MoneyItem	The database name of the item used as cash (inventory item).	'money'

🛡️ Admin & Permissions

Control who has access to administrative banking commands.

Config.GiveBankMoneyGroups = { "admin", "god" } -- Groups allowed to use the give command
Config.GiveMoneyCommand = 'givebank'            -- Command to give money by username

Config.RemoveBankGroups = { "admin", "god" }    -- Groups allowed to use the remove command
Config.RemoveMoneyCommand = 'removebank'        -- Command to remove money by username

🏦 Banking Features

Settings related to bank accounts, creation, and deletion.

• Config.CreatorOnly: If set to true, only the player who created a bank account can access it (prevents shared access unless credentials are shared).

• Config.DeleteAccount: If false, players cannot delete their bank accounts manually.

• Config.MaxAccountsPerLicense: Maximum number of bank accounts a single player (license) can own.

• Config.StartingCrypto: Amount of crypto currency a new account starts with.

• Config.DefaultAvatar: Default profile picture for bank accounts if none is set.

• Config.UseDiscordAvatar: If true, the script attempts to fetch the player's Discord avatar (requires bot token setup).

💳 Cards & Limits

Manage credit/debit card behavior, spending limits, and cooldowns.

Card Items

Define the inventory item names for physical cards.

Config.CardItem = {
    DebitCard = 'debit_card',
    PrepaidCard = 'prepaid_card',
    CreditCard = 'credit_card'
}

Limits & Cooldowns

• Config.CardSpendingLimit: Daily spending limit for cards (e.g., $5,000 for Prepaid).

• Config.CardBalanceLimit: Maximum balance a card can hold.

• Config.ResetCardLimitsInterval: Time in seconds to reset daily limits (Default: 10800 = 3 hours).

• Config.CardRegeneration:

  • EnableCooldown: Prevents spamming new cards.

  • CooldownTime: Time in seconds before a player can request a new card of the same type.

💸 Loan System

Configure the bank loan system, including interest rates and repayment terms.

Config.Loans = {
    Enabled = true,          -- Turn the loan system on/off
    OnlyPrimary = false,     -- If true, loans are restricted to the primary account
    MinLoanAmount = 1000,    -- Minimum request
    MaxLoanAmount = 500000,  -- Maximum request
    GuaranteePercent = 30,   -- % of loan held as security deposit
    GuaranteeSociety = 'governo', -- Society account receiving the guarantee
    
    Installments = { Min = 1, Max = 36 }, -- Repayment split limits
    InstallmentIntervalHours = 24,        -- Time between payments
}

Interest Rates

You can define tiered interest rates based on the loan amount.

InterestRates = {
    { min = 1000, max = 4999, percent = 3.0 }, -- 3% interest for small loans
    { min = 50000, max = 200000, percent = 10.0 } -- 10% interest for huge loans
}

📍 Locations (Banks & ATMs)

Bank Blips

Configure physical bank locations and blips on the map.

Config.BankLocation = {
    Pacific = {
        coords = vec4(242.4305, 225.6224, 106.2779, 157.3414),
        blip = { enabled = true, sprite = 108, color = 2, label = "Bank Pacific" }
    },
    -- Add more locations here...
}

ATMs

Define which props act as ATMs and the interaction distance.

Config.ATMModels = { 'prop_atm_01', 'prop_atm_02', 'prop_fleeca_atm' }
Config.ATMInteractRange = 1.5

⛏️ Crypto Mining & Warehouses

Settings for the physical crypto mining system.

• Config.CryptoMine["Buy"]: Configuration for the NPC who sells warehouses.

• Config.warehouses: List of purchasable mining warehouses with coordinates, price, and size.

• Config.CratePrice: Cost of a crate of mining parts.

• Config.RigPrice: Cost of a mining rig.

• Config.PriceKw: Electricity cost per Kw used.

• Config.CryptoProfitForMinuteForRig: How much crypto 1 rig generates per minute.

🧾 Billing System

If enabled, this allows specific jobs to send invoices.

• Config.BillingSystem: true to enable.

• Config.BillingAllowedJobs: List of jobs (and minimum grades) that can access the billing panel.

• Config.BillingSystemLocation: Physical locations where billing can be made (optional).

• Config.BillingOpenKey: Keybind to open the billing menu (Default: F5).

🔔 Notifications

Choose your notification provider.

• Config.NotificationSystem: Options: 'ox', 'esx', 'custom'.

• Config.NotificationFunctions: You can edit the code inside these functions to support a completely custom notification script if needed.

🖼️ UI Customization

Change the images displayed in the banking menu advertisements and calendar.

• Config.AdsImage: Links to images for the "Manage Account" and "Wallet" banners.

• Config.CalanderImage: Links to images for each month in the transaction history calendar.

🤖 Discord Integration & Logs

To monitor banking activity and enable advanced features (like Discord Avatars and Password Recovery), you must configure the Config.Log and Config.Bot sections.

📋 Discord Webhooks (Config.Log)

You can set up specific Discord Webhooks for different banking actions. This allows you to have a dedicated log channel for every type of transaction or admin action.

How to get a Webhook URL:

1. Create a channel in your Discord server (e.g., #bank-logs).

2. Right-click the channel > Edit Channel > Integrations > Webhooks.

3. Create a Webhook, copy the Webhook URL, and paste it into the configuration below.

Variable	Description
CreationAccount	Logs when a player creates a new bank account.
BuyWareHouse	Logs purchases of crypto mining warehouses.
RichargeCard	Logs when money is added to a prepaid/credit card.
BlockCard	Logs when a user blocks their card.
SendMoneyDashboard	Logs transfers made through the dashboard.
DepositMoneyDashboard	Logs deposits made through the dashboard.
TransferMoneyQuickDashboard	Logs quick transfers.
ChangePassword	Logs when a user changes their account password.
DeleteCredential	Logs when a saved login is removed.
SignOutAll	Logs when a user signs out from all devices.
AddAccount	Logs adding a shared/secondary account.
DeleteAccountPerma	Logs permanent deletion of a bank account.
WithdrawAtm	Logs ATM withdrawals.
DepositAtm	Logs ATM deposits.
SellCrypto / BuyCrypto	Logs cryptocurrency trading activity.
PinChange...	Logs PIN changes for Debit, Credit, or Prepaid cards.
GiveBankMoney	Logs use of the /givebank admin command.
RemoveBank	Logs use of the /removebank admin command.
Loan...	Logs Loan approvals, payments, and full repayments.

Example Configuration:

Config.Log = {
    CreationAccount = 'https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE',
    BuyWareHouse = 'https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE',
    -- ... add your other webhooks
}

🤖 Discord Bot Token (Config.Bot)

The Discord Bot Token is essential for two main features:

1. Forgot Password: Allows the script to send a DM to the user with a temp password.

2. Discord Avatar: If Config.UseDiscordAvatar is set to true, the script uses the bot to fetch the player's Discord profile picture for their bank profile.

How to get a Bot Token:

1. Go to the Discord Developer Portal.

2. Create a New Application.

3. Go to the Bot tab and click Add Bot.

4. Click Reset Token to generate a token and copy it.

5. Important: Under "Privileged Gateway Intents", enable Server Members Intent (so the bot can find users to fetch avatars).

Config.Bot = {
    Token = 'YOUR_BOT_TOKEN_HERE',
}

🧾 Billing & Society Integration (billing.lua)

The file billing.lua (server-side) is crucial for the billing system. It determines where the money goes when a player pays an invoice issued by a job (Police, Mechanic, Ambulance, etc.).

Since every server uses different resources to manage society funds (Boss Menus), you may need to edit this file to match your specific setup.

If you are using QBCore and you want KS-Bank to handle the society deposits (interacting with the standard bank_accounts table), you simply need to use the dedicated export inside this file.

The Function: AddMoneyToSocietyAccount

This function is triggered automatically whenever a bill is paid.

function AddMoneyToSocietyAccount(job, amount, reason)
    if ESX then
        -- Default ESX handling via esx_addonaccount
        TriggerEvent('esx_addonaccount:getSharedAccount', ('society_%s'):format(job), function(account)
            if account then
                account.addMoney(amount)
            end
        end)

    elseif QBCore then
        -- Default QBCore handling
        exports['KS-Bank']:AddMoney(job, amount, reason)
    else
        print('invalid framework')
    end
end

📬 Need Help or Support?

If you have any questions, need help with setup, or want to report a bug, feel free to join our support Discord:

👉 Join our Discord server