> For the complete documentation index, see [llms.txt](https://ambr4-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ambr4-scripts.gitbook.io/docs/scripts/banking-system/general-installation.md).

# General Installation

1. Upload `ambr4_banking` into your server resources, for example: `resources/[ambr4]/ambr4_banking`.
2. Keep folder name as `ambr4_banking`.
3. Ensure dependencies/framework start before this resource.
4. Set your framework and billing provider in `shared/config.lua`.
5. Start the resource: `ensure ambr4_banking`.
6. First boot will auto-create and auto-migrate required database tables/columns.

### Required Config

```lua
Config.Framework = "esx" -- "esx" | "qbcore" | "qbox"

Config.Billing = {
    Provider = "esx_billing", -- "esx_billing" | "qb_phone"
    QBPhoneResource = "qb-phone" -- used when Provider = "qb_phone"
}
```

### Start Order Examples

ESX:

```cfg
ensure oxmysql
ensure es_extended
ensure esx_addonaccount
ensure esx_billing
ensure ambr4_banking
```

QBCore:

```cfg
ensure oxmysql
ensure qb-core
ensure qb-banking
ensure qb-phone
ensure ambr4_banking
```

Qbox:

```cfg
ensure oxmysql
ensure qbx_core
ensure ambr4_banking
```

### Dependencies

<details>

<summary><a href="https://github.com/overextended/oxmysql">oxmysql</a></summary>

Required for all DB operations and automatic schema migrations.

</details>

<details>

<summary><a href="https://github.com/esx-framework/esx_core/tree/main/[core]/es_extended">es_extended</a> or <a href="https://github.com/qbcore-framework/qb-core">qb-core</a> or <a href="https://github.com/Qbox-project">qbox</a></summary>

Choose one framework through `Config.Framework`.

</details>

<details>

<summary><a href="https://github.com/overextended/ox_target">ox_target</a> (optional)</summary>

Only needed if you enable target interaction mode in config.

</details>

### Billing Integration (Quick)

If you use AMBR4-ready billing resources, no extra coding is needed.

1. Select provider in `ambr4_banking/shared/config.lua`.
2. Keep start order correct (`esx_billing`/`qb-phone` before `ambr4_banking`).
3. Restart billing resource + banking resource.

### Billing Integrations

* [ESX Billing Integration](/docs/scripts/banking-system/general-installation/billing-esx-integration.md)
* [QBCore Billing Integration](/docs/scripts/banking-system/general-installation/billing-qbcore-integration.md)
* [Custom Billing Integration](/docs/scripts/banking-system/general-installation/billing-custom-integration.md)

### Public Exports (ambr4\_banking)

```lua
exports['ambr4_banking']:AddIncome(target, amount, label)
exports['ambr4_banking']:AddExpense(target, amount, label)
exports['ambr4_banking']:AddBillingEntry(target, payload)
```

`target` can be player source, framework identifier/citizenid, or object with identifier/source fields.

Usage examples:

```lua
exports['ambr4_banking']:AddIncome(source, 350, 'Paycheck')
exports['ambr4_banking']:AddExpense(source, 1200, 'Vehicle repair')
```

### Quick Validation Checklist

1. Open bank UI and confirm account data loads.
2. Create one invoice from job script and check Billing History (`Pending`).
3. Pay invoice from bank modal and confirm instant status update (`Paid`).
4. Confirm Recent Activity updates after invoice payment.