Configuration Reference

Everything you can change lives in the config/ folder. This page explains each file and the most important settings. After changing a config file, restart the resource (ensure oxide-banking) for the change to take effect.

Config File Map

General Settings

File: config/config.lua

Security

File: config/config.lua

Scheduling And Time

File: config/config.lua

Banking runs on its own internal calendar. One "banking day" passes for every calendar day on your server's real clock. If the server was off at midnight, including during a nightly restart, the day is counted the next time it starts, so nothing is lost. Savings interest, recurring payments, and market updates are all measured in banking days.

Loan due dates, invoice due dates, and investment and CD maturity dates are real calendar dates.

Cards, Logging, Business, And Transfers

File: config/config.lua

Cards

Logging

These settings control what the bank sends to ox_lib's logger. That logger only sends anything if you have set up a logging service in ox_lib.

Business

Config.Business controls expense categories and invoice due dates, late fees, limits, and collection.

The invoice limits apply only to invoices players write from the banking screen. Invoices raised by other resources (fines, medical bills, vehicle finance) are not limited.

Late fees. An unpaid invoice is marked overdue the day after its due date. From then on the late fee is InvoiceLateFeePercent plus InvoiceLateFeeDailyPercent for every day past the due date, capped at InvoiceMaxLateFee. With the defaults, an invoice one day late carries a 6% fee, and one ten days late carries 15%. The screen shows the total a player owes, and that is what they are charged.

Collection. Once an invoice is InvoiceAutoDebitAfterDays days past its due date, the amount owed is taken from the debtor's bank account automatically. Only the full amount is ever taken — a debtor who cannot cover it is left alone and keeps accruing the fee. Whoever raised the invoice can still cancel it while it is overdue, so a mistake can be withdrawn before collection takes it. Set InvoiceAutoDebitEnabled = false to turn collection off and leave late fees and credit score damage as the only consequence.

Both run once per banking day. Admins can run them on demand with /forceinvoices, which only marks invoices and updates fees; /forceinvoices collect also collects, even when InvoiceAutoDebitEnabled = false. See Admin Commands.

Config.Business.ExpenseCategories ships with 7 default categories (supplies, utilities, vehicle, property, legal, marketing, other).

Credit Score

A player's score has two parts. Five weighted factors — payment history (35%), credit utilization (30%), length of history (15%), credit mix (10%) and new inquiries (10%) — produce a base score. Credit events such as an on-time payment or a loan going to collections add a bonus or penalty on top, which fades back toward zero over time. What the player sees is the two added together.

A player with no loans and no loan payments has nothing for the factors to measure, so their base score stays at defaultScore until they take out credit. Credit events, such as an overdue invoice, still move the score up or down from there.

The bank records these eventDeltas events itself: loan_payment_ontime, loan_paid_off, loan_opened, loan_defaulted, investment_completed, cd_matured, invoice_paid_ontime, invoice_paid_late, and invoice_overdue. The other keys in the shipped table (collateral_seized, hard_inquiry, account_opened, account_age_increase, credit_utilization_low, credit_utilization_high) only count when another script records them through the RecordCreditEvent or AddHardInquiry exports.

Three penalties are not in eventDeltas. They read from the loan config instead, so each has a single home:

Transfer delays and transaction caps

Config.TransferDelays makes transfers to other players take time to arrive instead of being instant. The sender's money leaves straight away, and the recipient receives it at the first hourly check after the delay is over. Players can pay the expedited fee to skip the wait, and a pending transfer can be cancelled before it completes.

Config.Transactions caps single deposits (MaxDepositAmount), withdrawals (MaxWithdrawAmount), and transfers (MaxTransferAmount) at 10000000 ($10M) by default.

Amounts are whole dollars. Players cannot enter cents or anything under $1, and fees are charged in whole dollars too: a fee set with cents, such as expeditedTransfer.fee = 2.5, is rounded down.

Tablet

File: config/config.lua

Phone

File: config/config.lua

Account Tiers And Account Types

File: config/accounts.lua

Tiers

Config.AccountTiers ships with three tiers:

• basic
• premium
• business

Keep these three tier names. The bank treats them as the lowest, middle and highest tier. You can change everything inside them, including the label.

Config.DefaultTier (default 'basic') is the tier every new player starts on.

Each tier defines:

• label and description
• monthlyFee — charged from the player's bank when they log in, once 30 real days have passed since the last charge. A player who cannot pay is moved down to Basic
• interestRate — yearly interest rate (see DaysPerYear)
• maxSharedAccounts — shared accounts the player can own
• dailyWithdrawLimit and dailyTransferLimit — how much the player can withdraw and send to other players per real day
• features — savings (savings accounts and CDs), investments, and overdraft with overdraftLimit (how much more than the bank balance a cash withdrawal may be). An overdraft withdrawal empties the bank balance and the rest is owed to the bank, shown on the banking screen. The next money that reaches the player's bank pays it back automatically. The prioritySupport, invoicing and expenseTracking flags are not currently used, and noATMFees is only shown as a label in the bank settings
• requirements — minBalance, creditScore, and jobBoss (must be the boss of their job) to upgrade to this tier

Account types

Config.AccountTypes includes:

• checking — the player's main personal account
• savings — earns extra interest, with a fee for withdrawing money deposited recently
• shared — accounts a player can share with other players
• job — business accounts tied to a job (police, mechanic, etc.)
• gang — not supported. The bank does not create gang or organization accounts

Only the savings entry is read by the bank: maxAccounts (default 3, savings accounts per player) and the settings below. The other entries, and the label, icon, allowMultiple, interestEarning and bossOnly fields, are not currently used.

These work the same on every supported framework (QBCore, QBX, ESX).

Savings notice period

Money paid into a savings account has to sit there for a while before it can be taken out for free. Three settings in Config.AccountTypes.savings control this:

A withdrawal takes the oldest money in the account first, so the fee only ever touches what is left over after the cleared money runs out. For example, an account holds $10,000 that has sat for weeks, and the player pays in $5,000 today. Withdrawing up to $10,000 costs nothing. Only the part taken from today's $5,000 is charged 1%. Interest the account earns is never charged.

The savings screen shows how much of each account is free to withdraw, and the withdrawal box shows the fee and the amount received before anything is confirmed.

Set withdrawalNoticeDays = 0 to charge nothing and let savings behave like a second checking account.

Savings goals

Config.SavingsGoals defines max goals per player (maxGoals, default 5) and the category list used by the UI.

Loans

File: config/loans.lua

Core loan settings

A loan application that is waiting for approval or still processing takes up one of the maxActiveLoans slots, the same as a funded loan.

How repayment works

A loan is split into instalments Config.TimeSettings.LoanPaymentInterval days apart. On each due date the instalment is taken from the borrower's bank account automatically, whether they are online or not. If the money is not there, the payment is recorded as missed and the next due date is one interval later. After Config.LatePayment.collectionsThreshold missed payments the loan goes to collections. Once the term is over, the whole remaining balance falls due.

Players can also pay by hand at any time:

• Only a payment that finishes an instalment, or clears the loan, counts toward the player's credit. Smaller payments still reduce the balance but do not build credit and do not move the due date.
• Pay Off settles the loan early and gives back the interest for the instalments that never ran.
• A loan in collections is no longer collected automatically, but it can still be paid from the bank screen. If wage garnishment is on, a share of each paycheck goes toward it until it is cleared.

If you change LoanPaymentInterval, or update from a version that collected loans differently, open loans are re-fitted to the new schedule the next time the server starts: the instalment is recalculated, and a loan that is being repaid has its term restarted from that day with its missed payments cleared, so nobody is charged late fees because the rules changed. Loans registered by another resource (vehicle finance) are never touched.

Total borrowing limit

Config.Loans.exposure caps how much debt one player can carry across all their loans, including vehicle loans registered by a dealership.

Built-in products

The shipped config includes three loan products:

• personal
• business
• emergency

Each product defines:

• amount range (minAmount, maxAmount)
• base yearly interest rate (baseInterestRate)
• term options in days (termOptions)
• eligibility requirements: minCreditScore, minAccountAge (banking days the player's bank account has existed), minIncome (checked against the player's bank balance), and jobBoss
• whether collateral is required (collateral)
• optional instant approval (instantApproval)

Shipped defaults in config/loans.lua:

None of the shipped products require collateral. A business loan of 100000 or more still waits for an admin because of Config.LoanApproval.manualApprovalThreshold (below).

External loan types

Config.Loans.externalTypes is used for externally managed loan records that still appear in the bank UI. The shipped config includes vehicle. See Vehicle Financing.

Approval, late fees, and collections

The file also defines:

• Config.CreditScoreRateModifiers — how much a credit score raises or lowers a loan's rate
• Config.LatePayment — the loan late fee (the higher of lateFee and lateFeePercent of the instalment, capped at maxLateFee), the credit penalties for late and missed payments, and collectionsThreshold
• Config.Loans.collections — wageGarnishment and garnishmentPercent (the share of each paycheck taken while a loan is in collections), and creditScoreImpact
• Config.LoanApproval — how applications are approved (below)

In Config.Loans.collections, the enabled, warningNotifications, assetSeizure and collateralHandlerResource settings are not currently used. Nothing in the current version seizes collateral.

Config.LoanApproval decides what happens to an application:

1. An amount at or above manualApprovalThreshold (default 100000) waits for an admin to use /approveloan, even on an instant-approval product.
2. A product with instantApproval = true, or an amount at or below autoApproveUnderAmount (default 100000), is funded straight away.
3. Anything else waits processingTime real hours (default 2), then is funded. If processingTime is 0, it waits for an admin instead.

Interest, Investments, And CDs

File: config/interest.lua

Interest

Config.Interest controls:

• enabled — turns account interest on or off
• calculationMethod — 'simple' or 'compound'
• minimumBalance — accounts below this earn nothing
• maxInterestPayout — cap on a single interest payment (for checking, per day since the last payment)
• accountTypeRates — account-type rate multipliers
• payoutFrequency — Not currently used

Where interest is paid:

• Checking earns the tier's rate. It is paid when the player logs in, for the real days since their last interest payment.
• Shared accounts the player owns are paid at the same moment, at the shared multiplier.
• Savings accounts are paid by the daily schedule.
• Job accounts do not earn interest, so the job and gang multipliers are not currently used.

Config.Interest.accountTypeRates multiplies the tier's base rate per account type. Savings defaults to 1.25, which keeps it below every certificate of deposit — savings can be withdrawn at any time, so it should pay less than money a player agrees to lock up. Raising it above the CD rates removes any reason to buy a certificate.

Investments

Built-in investment products:

Every product also needs a tier with the investments feature, which on the shipped config means Premium or Business.

expectedReturn and volatility are both annual figures. Each banking day one return is drawn per product and every position in that product moves by the same percentage, so two players holding the same fund get the same result and splitting a stake across several positions changes nothing.

When a position reaches its maturity date it stops accruing and is held at its value until the player withdraws it. Withdrawing a matured position carries no penalty.

A position can be cashed out before it matures. earlyWithdrawalPenalty is charged on the earnings only and shrinks the closer the position is to its term, so an early exit never returns less than the amount invested. A position that is at a loss is never penalised. Set the value to 0 to let players leave a product freely.

Dividends. A product with dividendRate (a yearly rate) pays that share of the position's value to the player's bank every dividendFrequency banking days. On the shipped config only real_estate pays one (3% a year, every 14 banking days). Config.Investments.dividendDefaults sets minHoldDays (real days a position must be held before its first dividend, default 7) and roundToNearest (dividends are rounded to this many dollars, default 1).

Market simulation. Config.Investments.marketUpdate controls the market. A trend's configured impact (crashImpact, boomImpact) is the total move it makes, spread across the days it lasts. A crash lasts one day, so it lands all at once. The trend shifts values in its own direction rather than scaling whatever they were already doing. The frequency setting is not currently used; the market moves on the InvestmentUpdateInterval schedule.

Booms, crashes and momentum move a fund around its expectedReturn; they do not add to it. Whatever odds and sizes you set here, the bank works out what they would pay on average and takes that off, so over a year a fund averages the return on its label. Change these settings to make the market calmer or wilder, and change expectedReturn to make a fund pay more or less.

Certificates of deposit

Rates are annual and prorated by term at purchase, so a 7-day CD at 4% pays 4% x 7/28.

Buying a CD needs a tier with the savings feature (Premium or Business on the shipped config).

A matured certificate must be redeemed in full; it cannot be withdrawn early for a penalty.

An early withdrawal pays back the deposit plus the interest earned up to that point, less the penalty charged on that interest. The deposit itself is never touched, so an early withdrawal returns at least what was put in.

Fees

File: config/fees.lua

Fees that belong to one feature are set with that feature instead: card prices in Config.Cards, monthly account fees on each tier in Config.AccountTiers, loan late fees in Config.LatePayment, invoice late fees in Config.Business, and the savings withdrawal fee in Config.AccountTypes.savings.

Wire transfer fees. Wire transfers are only sent by other scripts, through the ProcessWireTransfer export. The banking screen has no wire transfer option, so these fees are never charged unless such a script uses them.

Integration fees. Config.Fees.transactions.atm (ownBank, otherBank, outOfNetwork) and Config.Fees.transactions.externalTransfer (flat, percent, minFee, maxFee) are never charged by the bank itself: its own ATMs are free, and a transfer to another player only pays the expedited fee if the player chooses it. They are the amounts the CalculateATMFee and CalculateTransactionFee exports return, for an ATM or payment resource that wants to charge them. See Exports & Integration.

Config.FeeWaivers lists the fees each group does not pay: premium tier, business tier, and players whose bank balance is at or above highBalance.threshold. Each entry is a fee key, which is the path under transactions, for example wireTransfer.domestic or atm.otherBank.

Config.FeeDescriptions holds the labels shown on statements and fee previews for those keys.

Debug Settings

File: config/config.lua