# qb-banking: accounts, exports and SQL

`qb-banking` implements the bank/ATM interface, shared player accounts, job and gang accounts, and bank statements. It does **not** replace the checking balance in `Player.PlayerData.money.bank`. This reference is based on [upstream commit b2dee4e](https://github.com/qbcore-fivem/qb-banking/tree/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8), not older forks with different account models.

## Installation and dependencies

1. Install `qb-core` and `oxmysql`. The manifest imports `@oxmysql/lib/MySQL.lua` and the client-side PolyZone modules.
2. Import the **unmodified** [`banking.sql`](https://github.com/qbcore-fivem/qb-banking/blob/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8/banking.sql) into a staging database. Back up existing account data before migrating an old banking script.
3. Start the required dependencies before `qb-banking`. Confirm no second resource is defining a competing banking UI or society-account schema.
4. Join with a test character, open a bank and an ATM, then test deposits and withdrawals with permitted and insufficient balances.

The upstream SQL creates exactly two tables:

| Table | Purpose |
| --- | --- |
| `bank_accounts` | Named shared, job and gang accounts; includes `account_name`, `account_balance`, `account_type` and `users` |
| `bank_statements` | Transaction history with `citizenid`, `account_name`, `amount`, `reason` and `statement_type` |

`bank_accounts.account_type` permits **`shared`, `job` and `gang`**. The personal checking account is represented using `PlayerData.money.bank`; do not change the SQL enum to an invented `personal` or `business` type.

## Configuration

These are the keys present in upstream [`config.lua`](https://github.com/qbcore-fivem/qb-banking/blob/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8/config.lua):

| Key | Current default | What it controls |
| --- | --- | --- |
| `Config.useTarget` | `GetConvar('UseTarget', 'false') == 'true'` | Whether target interaction is enabled |
| `Config.atmModels` | Four GTA ATM prop names | Models used for nearby ATM detection |
| `Config.useDailyLimit` | `true` | Enables the configured withdrawal limit flow |
| `Config.dailyLimit` | `5000` | Configured withdrawal limit |
| `Config.maxAccounts` | `2` | Maximum additional accounts per character |
| `Config.blipInfo` | Bank blip properties | Bank map markers |
| `Config.locations` | Bank coordinates | Bank interaction locations |

Do not use `Config.EnableATMs`, `Config.InterestRate` or other keys from unrelated bank forks unless the installed revision actually defines them.

## Server exports

Call these from **server code**. The names and function arguments below come from [`server.lua`](https://github.com/qbcore-fivem/qb-banking/blob/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8/server.lua).

| Export | Arguments | What it does |
| --- | --- | --- |
| `CreatePlayerAccount` | `playerId, accountName, accountBalance, accountUsers` | Creates a named `shared` account for an online player's citizen ID |
| `CreateJobAccount` | `accountName, accountBalance` | Creates a `job` account |
| `CreateGangAccount` | `accountName, accountBalance` | Creates a `gang` account |
| `CreateBankStatement` | `playerId, account, amount, reason, statementType, accountType` | Stores a bank statement |
| `AddMoney` / `AddGangMoney` | `accountName, amount, reason` | Credits a **named banking account** |
| `RemoveMoney` / `RemoveGangMoney` | `accountName, amount, reason` | Debits a **named banking account** |
| `GetAccount` / `GetGangAccount` | `accountName` | Returns the named account table or `nil` |
| `GetAccountBalance` | `accountName` | Returns the named account balance, or `0` when absent |

The gang-named exports are aliases of the corresponding generic implementations. `CreateAccount`, `GetBalance`, and `OpenBankingMenu` are **not** exported by this upstream revision.

### Read a job account without changing it

~~~lua filename="server.lua"
local account = exports['qb-banking']:GetAccount('police')
if not account then
    print('No police banking account has been initialized')
else
    print(('Police account balance: %s'):format(account.account_balance))
end
~~~

`GetAccountBalance('police')` returning `0` does **not** distinguish a missing account from an empty one; call `GetAccount` when that distinction matters.

### Credit a verified job account

Only a server-owned workflow with **independently validated authorization and amount** should modify an account. `AddMoney` does not perform your job/role authorization for you.

~~~lua filename="server.lua"
-- Within an already authorized, server-owned payout path:
local accountName = 'police'  -- Derived from trusted server configuration
local amount = 250            -- Derived from trusted server rules
local account = exports['qb-banking']:GetAccount(accountName)
if account and amount > 0 then
    exports['qb-banking']:AddMoney(accountName, amount, 'Approved department payment')
end
~~~

Do not accept `accountName`, `amount` or `reason` directly from a client event and use them without server-side validation.

## Callbacks versus network events

The bundled client uses `QBCore.Functions.TriggerCallback` for these internal banking flows:

- `qb-banking:server:openBank` and `qb-banking:server:openATM`
- `qb-banking:server:withdraw` and `qb-banking:server:deposit`
- `qb-banking:server:internalTransfer` and `qb-banking:server:externalTransfer`
- `qb-banking:server:orderCard`, `openAccount`, `renameAccount` and `deleteAccount` (all with the `qb-banking:server:` prefix)
- `qb-banking:server:addUser` and `qb-banking:server:removeUser`

These are **framework callbacks**, not `qb-banking:server:depositMoney`/`withdrawMoney` network events. Their payloads belong to the installed UI, not a documented general-purpose export API.

Job and gang accounts are initialized when the bank opens for an applicable player. A separate resource that needs the balance before first bank use should verify account initialization instead of assuming the row already exists.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| `bank_accounts` or `bank_statements` missing | Verify the official `banking.sql` was imported into the actual oxmysql database |
| Account lookup returns `nil` | Check the exact `account_name` and whether an account was created/initialized |
| Account balance is wrong | Determine whether the integration used the named society account or `PlayerData.money.bank` |
| ATM interface does not open | Confirm `Config.atmModels`, target convar, PolyZone startup and client console |
| An export or event cannot be found | Compare its spelling and side with `server.lua`; do not copy APIs from a different bank fork |
| Migration from an older banking script breaks | Diff table columns and account types on staging; do not overwrite balances with a new demo schema |

## Update checklist

1. Pin the deployed banking commit; review `config.lua`, `server.lua`, `client.lua` and `banking.sql` together.
2. Back up existing accounts and statements before any SQL migration.
3. Verify authorized and unauthorized transfers, account creation limits, withdrawal bounds and UI callbacks on a test server.
4. Audit custom money-changing events separately: this page documents the upstream interface, **not** a security guarantee.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-banking/tree/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8) · [Server exports and callbacks](https://github.com/qbcore-fivem/qb-banking/blob/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8/server.lua) · [Configuration](https://github.com/qbcore-fivem/qb-banking/blob/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8/config.lua) · [Schema](https://github.com/qbcore-fivem/qb-banking/blob/b2dee4eae9eb9374f6adb303d9bf31cb1ddc3be8/banking.sql)

For server-side money handling see [QBCore functions](/docs/core/functions) and [safe server events](/docs/security/safe-server-events).
