Installation Guide
Step-by-step setup for oxide-banking — prerequisites, load order, database, the bank card item, updating from an older version, and first checks in game.
Step-by-step setup for oxide-banking. Follow the steps in order — most issues come from skipping one.
Prerequisites
oxide-banking works on QBCore, QBX, and ESX. It detects your framework automatically — there is nothing framework-specific to configure.
Required resources
| Resource | Purpose |
|---|---|
ox_lib | Server callbacks, logging, and translations |
oxmysql | Connects the server to your MySQL database |
o-link | Connects banking to your framework — players, money, jobs, inventory, targeting, notifications |
| Framework | One of qb-core, qbx_core, or es_extended |
If you already run other Oxide resources, you have all three.
You also need an inventory that o-link supports, such as ox_inventory or qb-inventory. Debit cards are inventory items that carry a card number, and banking places and reads them through o-link.
ESX's built-in inventory is not supported
On ESX, use ox_inventory or another inventory o-link supports. Without one, players cannot hold debit cards and ATMs will not open.
Optional resources
| Resource | What it adds |
|---|---|
| A target resource | Targeting-eye interaction on banks and ATMs. Any target o-link supports works, such as ox_target or qb-target |
oxide-tablet | A Banking app on the tablet — see Tablet app below |
oxide-phone | A Banking app and balance widget on the phone (needs o-link 1.11.0 or newer) — see Phone app below |
Installation Steps
Remove your old banking resource
oxide-banking replaces your server's existing banking script. Running two banking systems at once causes conflicts, so remove or disable the old one first:
- QBCore: remove
qb-banking(it ships with the default server). Move the folder out ofresources/[qb]or comment out itsensureline. Do not just leave it —oxide-bankingtakes over theqb-bankingname, and both cannot be running at the same time. - QBX: disable whatever banking script you use (for example
Renewed-Banking). - ESX: disable
esx_bankingor any other banking script. Keepesx_addonaccountrunning — banking uses it to stay in sync with your society accounts (see ESX society accounts).
Older scripts that talk to qb-banking keep working: oxide-banking answers to that name automatically.
Add the resource
Place the oxide-banking folder inside your server's resources folder. If you run other Oxide resources, put it in your [oxide] folder next to them. The folder must be named exactly oxide-banking.
Set the startup order
Open your server.cfg (the text file that tells your server which resources to start) and make sure banking starts after your framework and o-link. See Load Order below.
Set up the database
Open sql/install.sql in your database tool (HeidiSQL, phpMyAdmin, etc.) and run it against your server's database.
This creates all the banking tables — accounts, statements, cards, loans, credit scores, security, and reports. It is safe to run more than once; it will not overwrite existing data.
Updating an existing install? Run the files in sql/migrations/ as well — see Updating From An Older Version.
Add the bank card item
Players receive a bank_card item when they order a debit card, so your inventory needs to know what that item is. If your items file already has a bank_card entry, leave it as it is and skip this step.
Common on QBX and ESX. Copy the ['bank_card'] entry from itemimages/ox_inventory_items.lua in the resource folder into ox_inventory/data/items.lua, above that file's final closing brace:
['bank_card'] = { label = 'Bank Card', weight = 0, stack = false, close = true, description = 'A personal bank debit card' },Then copy itemimages/bank_card.png into ox_inventory/web/images/.
Default on QBCore. Add this to qb-core/shared/items.lua:
bank_card = { name = 'bank_card', label = 'Bank Card', weight = 0, type = 'item', image = 'bank_card.png', unique = true, useable = true, shouldClose = true, description = 'A personal bank debit card' },Also copy itemimages/bank_card.png from the resource folder into your inventory's images folder so the card shows a picture (the item still works without one).
Restart your inventory resource (or the server) after adding the item.
Review the settings
Open the files in the config/ folder and adjust them to taste — bank locations, fees, loan products, interest rates, and more:
config/config.lua— general settings, security, cards, business and invoices, transfers, credit score, tabletconfig/accounts.lua— account tiers, the savings account rules, and savings goalsconfig/loans.lua— loan products and approval rulesconfig/interest.lua— interest, investments, CDsconfig/fees.lua— transfer, tier change and overdraft fees, and who gets fees waived
The defaults work fine out of the box. See Configuration for what each setting does.
Start the server
The interface is pre-built and ships with the resource in web/dist — there is nothing to compile or build.
Load Order
Every Oxide resource follows the same four-tier order in server.cfg:
# 1. Framework — everything your framework requires (qb-core, es_extended, qbx_core, etc.)
ensure <framework>
# 2. Scripts — your other resources (phone, inventory, garages, etc.)
ensure <your-other-scripts>
# 3. o-link — the bridge. Starts after your framework/scripts, before any Oxide resource.
ensure o-link
# 4. Oxide resources — keep these together, ideally in a folder named [oxide]
ensure oxide-bankingIf you run several Oxide resources, put them all in a folder named [oxide] and start them with a single ensure [oxide] line in tier 4.
On ESX, esx_addonaccount is part of your framework, so it belongs in tier 1 and starts before banking.
Updating From An Older Version
install.sql only creates tables that do not exist yet — it will not add new columns to tables you already have. The files in sql/migrations/ do that.
Back up your database
Take a full backup before running any migration.
Run the migrations
Run each file in sql/migrations/ once, before you start the new version:
credit_hybrid_and_market_drift.sqlsavings_notice_period_and_invoice_fees.sqloverdraft_owed.sql
Each one is safe to run more than once.
MySQL 8
The migrations are written for MariaDB. On MySQL 8, remove IF NOT EXISTS from each ADD COLUMN and ADD INDEX line, and skip any column that already exists.
Copy the new settings
Copy the new settings from the shipped config/ files into your own config files. Several unused settings were removed from config/fees.lua — see Fees.
Restart the whole server
Restart the server, not only the resource. New versions can add new files, which only register on a full server start.
What happens to existing data on the first start:
- Savings balances are dated from the day each account was opened, so money in an account older than the notice period comes out free. In an account opened less than
withdrawalNoticeDaysago, the existing balance becomes free once the account reaches that age. - Open loans move onto the current repayment schedule automatically — see How repayment works.
If you see errors about missing columns such as base_score, late_fee, daily_drift, or overdraft_owed, a migration has not been run.
Checking That It Works
- Start the server and check the console —
ox_lib,oxmysql,o-link, andoxide-bankingshould all start without errors. You should see[oxide-banking] Banking system initialized successfully!. - Join the server. Bank icons should appear on the map (if
Config.Blips.enabled = true). - Walk to a bank (Legion Square Fleeca is a good test) and open it. The banking screen should show your balance.
- Order a debit card from the banking screen, then walk to an ATM and use the card. The ATM screen should open after you enter your PIN.
- Make a small deposit and withdrawal and confirm your balance updates.
If any of these fail, see Troubleshooting.
Good To Know
Targeting vs. walk-up prompts
Config.UseTarget = true (default) — players use the targeting eye on banks and ATMs. This works with any targeting resource o-link supports, such as ox_target or qb-target.
Config.UseTarget = false — players walk up to a bank or ATM and press E instead. Use this if your server does not run a targeting resource.
ESX society accounts
On ESX servers with esx_addonaccount installed, oxide-banking automatically keeps society accounts (e.g. society_police, society_cardealer) in sync. Money added through either system shows up in both.
- Keep
esx_addonaccountrunning alongsideoxide-banking - Your existing ESX job scripts that pay into society accounts keep working unchanged
- Society balances appear in the banking app with full statement history
No setup needed — banking detects ESX and esx_addonaccount on its own when the server starts.
Tablet app
If oxide-tablet is running, a Banking app appears on the tablet automatically. Bank locations and ATMs still open the bank's own window. To turn the tablet app off, set Config.Tablet.UseTablet = false in config/config.lua. See Tablet.
Phone app
If oxide-phone is running, a Banking app appears in the phone's App Store, beside the phone's own Wallet app. To give every phone the Banking app from the start, add banking to the phone's preinstalled apps (/phone settings → Home & Apps → Store). To turn the app off, set Config.Phone.UsePhone = false in config/config.lua. See Phone.
Needs o-link 1.11.0 or newer
With an older o-link, the bank works as before and the phone app does not appear.
Translations
The banking screen and most messages come from locales/en.json. To translate the bank, see Localization.
Next Steps
- Features — everything the bank can do
- Configuration — every setting explained
- Admin Commands — admin commands
- Exports & Integration — for developers integrating other scripts
- Troubleshooting — common problems and fixes
Oxide Banking
Full banking system for FiveM — personal, shared and job accounts, debit cards, loans, credit scores, savings, investments, invoicing, and account security.
Configuration Reference
Every oxide-banking config file and setting — security, the banking schedule, cards, invoices, credit scores, transfers, tiers, savings, loans, investments, CDs, fees, and the tablet and phone apps.