> For the complete documentation index, see [llms.txt](https://wiki.qfdevelopers.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.qfdevelopers.com/scripts/banking-v2/additional-informations.md).

# Additional Informations

Page dedicated to Additional Informations about our Banking \[V2].

#### Core Features

* **Universal Framework Support:** Works with ESX, QBCore and QBox, detected automatically, with ox, qb, ps, lj and qs inventories and any other through a bridge.
* **Everything in Game:** Banks, branches, ATMs, offices, the exchange, the economy and permissions are set in the admin panel. No coordinates in config files.
* **Self-Repairing Database:** Tables and columns are created and checked on every start. No SQL to import.
* **Banks as Businesses:** Players buy banks at the bank exchange, hire staff with signed contracts, set their own offer and run them from a management office.
* **Accounts, Cards and Products:** Main and personal accounts, cards with a PIN checked on the server, transfers with one-time codes, savings, term deposits and loans with a credit rating.
* **Real Cash:** Branch vaults and ATMs of private banks hold physical cash, restocked from the central bank or by the bank's own convoy.
* **Convoys and Robberies:** A full convoy job with real crates, and a built-in convoy robbery paying dirty money. Exports for your own ATM and vault robberies.
* **Billing:** Fines, invoices, taxes and sale contracts built in, replacing qf\_billing, with an optional link to the QF MDT \[V2] tablets.
* **Papers as Items:** Statements, contracts, cheques, titles, receipts and bills shown to the people around like MDT documents.
* **Character Photos:** Players are shown with their character photo everywhere (qf\_identity or your own source).
* **Backward Compatible:** Provides `qf_banking` and `qf_billing`, with their exports and events, and imports their data.

***

#### Server Security

Every amount, permission and distance is checked on the server; the interface only asks. PINs are checked on the server and never logged. Money moves in locked operations written to the ledger, so a restart in the middle of a sale, a cheque, a deposit or a convoy is settled on the next start instead of losing or doubling money. Every bank request is rate limited per player, and transfers from a set amount need a one-time code sent to the account owner.

***

#### Moving from V1 and qf\_billing

**From Banking V1 (`qf_banking`):**

1. Stop `qf_banking` and start `qf_banking_v2` instead. Scripts calling `exports.qf_banking` or depending on `qf_banking` keep working.
2. Optional: paste V1's `Config.AtmModels`, `Config.Zones` and `Config.Banks` into `config/legacy.lua`. The import then adds V1's bank peds as branches and its ATM points as ATMs of the state bank.
3. Run `bankadmin import-v1` in the server console. The report shows whether the imported history matches V1 row for row and dollar for dollar.

V1 tables are only read, so you can switch back at any time. The import can be repeated: rows already imported are skipped.

{% hint style="warning" %}
Differences from V1: `AddMoney` and `RemoveMoney` return `false` when the player's main account is frozen in the admin panel, amounts are whole dollars, and vRP is not supported. The event `qf_banking/addBankHistory` is only accepted from server scripts.
{% endhint %}

**From our Billing System (`qf_billing`):**

Remove `ensure qf_billing`. Scripts calling `exports.qf_billing` keep working. To bring the old bills over, run `bankadmin import-billing` in the server console: the `billing` and `billing_income_chart` tables are copied, nothing in them is changed, and a second run skips the bills already imported.

***

#### Developer API (Exports & Events)

{% tabs %}
{% tab title="Server Exports" %}
Every export below is called on `exports.qf_banking_v2`. The V1 and qf\_billing exports are also served as `exports.qf_banking` and `exports.qf_billing`. Amounts are whole numbers.

**Banking V1 (compatible)**

| Export                                                                                  | Description                                                                        |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `GetAccountBalance(playerId)`                                                           | Bank balance of the player's main account.                                         |
| `AddMoney(playerId, amount, title?)`                                                    | `true` / `false`.                                                                  |
| `RemoveMoney(playerId, amount, title?)`                                                 | `true` / `false`.                                                                  |
| `LogTransaction(playerId, amount, type, accountType, before, targetId?, targetBefore?)` | Writes a history row after your script moved the money.                            |
| `GetPlayerAccounts(identifier)`                                                         | `{ { number, type = 'main' \| 'current', label?, bankId, balance } }`, main first. |

**Robberies**

Limits, police count and cooldowns come from **Admin → Robberies**.

| Export                             | Description                                                                                                                                                 |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetAtmCash(atmId)`                | `cash, capacity` of a placed ATM.                                                                                                                           |
| `RobAtm(atmId, source?, pct?)`     | Takes `pct` % of the ATM's cash and pays it to `source`. Returns the amount, or `0` and `'disabled'`, `'not_enough_police'`, `'cooldown'` or `'not_found'`. |
| `RobBranchVault(source, branchId)` | Takes a share of the bank's treasury. Returns the amount, or `0` and `'disabled'`, `'cooldown'`, `'not_enough_police'` or `'empty'`.                        |
| `CrackCassette(source)`            | Opens a stolen ATM cassette the player carries and pays the cash inside.                                                                                    |
| `GetConvoys()`                     | Ids of the convoys on the road now.                                                                                                                         |
| `GetConvoy(id)`                    | `{ id, serial, bankId, branchId, step, van, plate, crew, crates }`, or `nil`. The van also carries the state bag `qfbConvoy`.                               |
| `GetConvoyByVehicle(entity)`       | The convoy a vehicle belongs to, or `nil`.                                                                                                                  |
| `RobConvoy(source, convoyId)`      | For a script that opens the van its own way: takes one cash crate and gives `source` a loot bag. Returns the value, or `0` and a reason.                    |

```lua
local amount, reason = exports.qf_banking_v2:RobAtm(atmId, source)
if amount == 0 then
    TriggerClientEvent('myrobbery:notify', source, reason)
end
```

**Billing (qf\_billing compatible)**

| Export                                                                 | Description                                                                             |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `CreateInvoice(source, targetPlayer, items, invoiceType?)`             | Issues an invoice from `source` to a player. `items`: `{ { label, price, quantity } }`. |
| `CreateInvoiceForSociety(source, targetSociety, items, invoiceType?)`  | The same, addressed to a society.                                                       |
| `GetPlayerInvoices(source, cb)`                                        | `cb({ personal, society, sent = { personal, society } })`.                              |
| `GetUnpaidInvoicesCount(source, cb)` / `HasUnpaidInvoices(source, cb)` | Unpaid bills of the player.                                                             |
| `ForcePayInvoice(invoiceId, payerSource, cb)`                          | Pays the bill from the payer's bank account without asking.                             |
| `CancelInvoice(invoiceId, cb)`                                         | Cancels an open bill.                                                                   |
| `GetInvoiceById(invoiceId, cb)`                                        | One bill.                                                                               |
| `GetPlayerStatistics(source, cb)` / `GetSocietiesList(source, cb)`     | Income chart and recent payments, the billing factions.                                 |
| `AddIncomeToChart(identifier, society, amount)`                        | Adds an amount to the income chart.                                                     |
| `PayBill(billId, payerSource)`                                         | A citizen pays a bill by the rules of the Bills page. `true, bill` or `false, reason`.  |

**Taxes**

| Export                                 | Description                                                                                              |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `PayIncomeTax(target, gross, origin?)` | Withholds income tax from a salary your script already paid to the player's bank. Returns the tax taken. |
| `GetTaxRates()`                        | `{ vat, income, transfer, wealth, wealthThreshold, ownership }` (0 for a tax that is off).               |

**MDT tablets**

For the QF MDT \[V2] tablets and your own: `IsIntegrationEnabled(tablet)`, `GetIntegrationFaction(tablet)`, `GetTariff(faction)`, `SaveTariffEntry(faction, entry, source)`, `DeleteTariffEntry(faction, id, source)`, `IssueFine(issuerSource, targetIdentifier, data)`, `IssueInvoice(issuerSource, targetIdentifier, data)`, `CancelFine(id, source)`, `GetCitizenFines(identifier, opts?)` and `GetFineStatus(id)`. Every price is checked against the faction's tariff on the server. The full reference is in `docs/MDT_INTEGRATION.md` inside the resource.

```lua
if GetResourceState('qf_banking_v2') == 'started' and exports.qf_banking_v2:IsIntegrationEnabled('police') then
    local ok, bill = exports.qf_banking_v2:IssueFine(source, citizenId, {
        items = { 'T-12' },          -- tariff codes or ids
        reason = 'Speeding',
        externalRef = reportId,      -- the same reference is never billed twice
    })
end
```

{% endtab %}

{% tab title="Server Events" %}

| Event                                                        | Arguments                                                  |
| ------------------------------------------------------------ | ---------------------------------------------------------- |
| `qf_banking_v2:onTransaction`                                | The booked transaction                                     |
| `qf_banking_v2:notice`                                       | `identifier, notice` (for phone scripts)                   |
| `qf_banking_v2:loanApproved` / `loanDefault`                 | The loan                                                   |
| `qf_banking_v2:chequeBounced`                                | The cheque                                                 |
| `qf_banking_v2:bankInsolvent`                                | The bank                                                   |
| `qf_banking_v2:atmRobbed` / `vaultRobbed` / `cassetteOpened` | The robbery                                                |
| `qf_banking_v2:convoyRobbed`                                 | `source, { id, serial, bankId, branchId, insider }`        |
| `qf_banking_v2:server:ownerChanged`                          | A bank changed owner                                       |
| `qf_banking_v2:server:staffRemoved`                          | `bankId, identifier` (fired or quit)                       |
| `qf_banking_v2:server:banksChanged`                          | Banks were changed                                         |
| `qf_banking_v2:server:settingChanged`                        | A setting was saved in the admin panel                     |
| `qf_banking_v2:server:convoyStarted`                         | `id`                                                       |
| `qf_banking_v2:server:convoyEnded`                           | `id, success, reason`                                      |
| `qf_banking_v2:server:convoyOrder`                           | `id, bankId`                                               |
| `qf_banking_v2:billing:billCreated`                          | `bill`                                                     |
| `qf_banking_v2:billing:fineIssued`                           | `bill`                                                     |
| `qf_banking_v2:billing:billPaid` / `finePaid`                | `bill`                                                     |
| `qf_banking_v2:billing:billClosed`                           | `bill` (rejected or canceled)                              |
| `qf_banking_v2:billing:billOverdue`                          | `bill`                                                     |
| `qf_banking_v2:billing:tariffChanged`                        | `faction, action, entry`                                   |
| `qf_banking_v2:billing:integrationChanged`                   | `tablet, enabled, faction`                                 |
| `qf_banking_v2:contracts:completed`                          | `contract` (a sale was paid and the subject changed hands) |

Events your scripts can trigger on the server:

* `qf_banking/addBankHistory`: V1 history event, only from server scripts (`TriggerEvent`).
* `qf_banking_v2:taxes:income` (`target, gross, origin?`): the same as `PayIncomeTax`.

```lua
AddEventHandler('qf_banking_v2:billing:finePaid', function(bill)
    print(('%s paid fine #%d of %d'):format(bill.target.name, bill.id, bill.amount))
end)
```

{% endtab %}

{% tab title="Client Exports" %}

| Export / Event                                   | Description                                            |
| ------------------------------------------------ | ------------------------------------------------------ |
| `exports.qf_banking_v2:OpenBilling(view?)`       | Opens the billing tablet, on `'bills'` or `'faction'`. |
| `exports.qf_banking_v2:OpenBillingFromPhone()`   | Opens the player's bills from a phone app.             |
| `exports.qf_billing:OpenBillingUI()`             | The qf\_billing export, opens the bills.               |
| `qf_banking_v2:client:openBillingPhone`          | Client event, same as `OpenBillingFromPhone`.          |
| `qf_banking/openBankUI` / `qf_banking/openATMUI` | V1 client events, open the bank and the ATM as before. |
| {% endtab %}                                     |                                                        |

{% tab title="Editable Hooks" %}
The hooks are in `server/editable.lua` and `client/editable.lua`. Money never moves inside a hook; hooks decide, show or react. A missing or broken hook falls back to its default.

**Server**

| Hook                                                                           | Purpose                                                                         |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `CanOpenBank(source, branch)` / `CanUseATM(source, atm)`                       | Extra conditions before a branch or an ATM opens.                               |
| `GetPlayerDisplayName(source)`                                                 | The name shown on accounts, transfers and papers.                               |
| `GetPlayerPhoto(identifier)`                                                   | The character photo shown in the interface (qf\_identity by default).           |
| `OnTransaction(transaction)`                                                   | After every booked transaction.                                                 |
| `OnLoanOverdue(loan)` / `OnLoanDefault(loan)`                                  | A missed instalment and a loan in collection.                                   |
| `AdjustCreditScore(identifier, score)`                                         | Change a computed credit score.                                                 |
| `OnBankOwnerChanged(bank, from, to)`                                           | A bank was bought, sold or seized.                                              |
| `OnEmployeeHired` / `OnEmployeeFired` / `SyncEmployeeJob`                      | Staff changes and the framework job.                                            |
| `CountPolice()`                                                                | Police on duty for robberies (`police`, `sheriff`, `state`, or `leo` jobs).     |
| `OnRobberyStarted(source, kind, data)`                                         | Send your dispatch alert from the server.                                       |
| `GiveRobberyLoot(source, amount, kind)` / `CanOpenCassette`                    | How robbery loot is paid and who may open a cassette.                           |
| `SendAuthCode(source, code, info)` / `SendPhoneNotification(identifier, data)` | One-time codes and bank notices on a phone (lb-phone example in the file).      |
| `OnBranchHours(branch, open)`                                                  | A branch opened or closed: lock your doors, switch lights.                      |
| `GiveVehicleKeys(source, vehicle, plate)` / `RemoveVehicleKeys`                | Keys of the convoy van and of sold vehicles (the picked key script by default). |
| `OnConvoy(kind, data)`                                                         | A convoy started, was delivered or failed.                                      |
| `GetIncomeTax(identifier, gross, origin, tax)`                                 | Change the income tax withheld.                                                 |
| `GetInvoices(source, identifier)`                                              | Another billing script, when the built-in billing is off.                       |
| `GetOwnedVehicles` / `TransferVehicle`                                         | Vehicles for sale contracts (owned\_vehicles / player\_vehicles by default).    |
| `GetOwnedProperties` / `TransferProperty`                                      | Your housing script for sale contracts.                                         |

**Client**

| Hook                                                                    | Purpose                                                            |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `PlayATMAnimation`, `PlayTellerAnimation`, `PlayAnimation(kind, prop?)` | Animations and props of every bank action.                         |
| `PlaySound(kind)` / `PlayBranchAlarm(branch)`                           | Sounds and the vault alarm.                                        |
| `OnBranchEnter` / `OnBranchExit`                                        | The player walks into or out of a branch.                          |
| `ShowHelp` / `HideHelp` / `GetInteractKey`                              | Your own TextUI and the default interaction key.                   |
| `DrawMarker(kind, coords)` / `DrawActivity(coords, label, meters)`      | Markers without a target and the convoy pointers.                  |
| `SetGPS(coords)`                                                        | Waypoints from the map.                                            |
| `OnRobberyAlert(data)` / `SendDispatch(data)`                           | Robbery alerts; ps-dispatch and cd\_dispatch examples in the file. |
| `IsRestrained()`                                                        | Blocks the bank while the player is cuffed or escorted.            |
| `OpenBilling()` / `OpenBillingFromPhone()`                              | Opening bills from the bank and from a phone.                      |

The full list with every argument and default is in `docs/HOOKS.md` inside the resource.
{% endtab %}
{% endtabs %}

***

#### Frequently Asked Questions (Q\&A)

**Q: Where are the coordinates of banks and ATMs?**\
A: In the database. Open `/bankadmin` → **Branches** or **ATMs**, stand where you want the place and press **Add here**.

**Q: Players do not get cards, cheques or papers.**\
A: The items are missing from your inventory. The console lists them on start and **Admin → Items** marks them. Paste the definitions from `install/` and copy the images.

**Q: A card item does not tell which card it is.**\
A: Your inventory keeps no item metadata (the ESX default inventory). ATMs then offer the player's cards from the bank instead, which works the same for players.

**Q: The ATM says it has no cash.**\
A: ATMs of private banks hold real cash. Staff pack cassettes from the branch vault and load them at the ATM, or an admin fills it in **Admin → ATMs**. To turn real cash off, set **Admin → ATMs → Cash in ATMs** to off.

**Q: A branch cannot issue cards or pay out cash.**\
A: Its vault is empty. The bank orders stock in its management office (**Vault**), delivered by the central bank or by its own convoy.

**Q: The crew cannot start the convoy van.**\
A: Pick your key script in **Admin → Economy → Convoys → Vehicle keys**, or set `custom` and connect it in `bridge/vehiclekeys.server.lua` (see [Vehicle keys](https://wiki.qfdevelopers.com/scripts/banking-v2/configuration.md#vehicle-keys)).

**Q: Faction bills are paid but the society gets nothing.**\
A: The society functions in `bridge/framework.server.lua` do not match your society resource. Payments that fail there are refunded to the payer and the bill stays unpaid.

**Q: Fines from my MDT do not reach the bank.**\
A: Both switches must be on: the tablet in **Admin → Billing → Service tablets** and the integration option in the MDT's own config. The tablet's billing faction must exist in **Billing → Units**.

**Q: Can I put my old V1 bank locations back?**\
A: Yes. Paste V1's config into `config/legacy.lua` and run `bankadmin import-v1` in the console.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.qfdevelopers.com/scripts/banking-v2/additional-informations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
