# Configuration

## Banking Script Configuration Guide

This guide covers the configuration options for the NeedForScripts Banking Script, including ATM models, bank locations, and general settings. It also provides information on available functions and events for integration with other scripts.

### Configuration Files

#### 1. atms.lua

This file contains the ATM models to check when using the card item.

```lua
return {
    2930269768,
    3168729781,
    506770882,
    3424098598
}
```

Add or remove model hashes as needed for your server.

#### 2. banks.lua

This file defines bank locations and blip settings.

```lua
return {
    blip = {sprite = 207, color = 1}, -- remove this if you want to hide blips
    positions = {
        vec3(150.266, -1040.203, 29.374),
        vec3(-1212.980, -330.841, 37.787),
        vec3(-2962.582, 482.627, 15.703),
        vec3(-112.202, 6469.295, 31.626),
        vec3(314.187, -278.621, 54.170),
        vec3(-351.534, -49.529, 49.042),
        vec3(241.727, 220.706, 106.286),
        vec3(1175.0643310547, 2706.6435546875, 38.094036102295)
    }
}
```

Modify the `positions` table to add or remove bank locations. Adjust the `blip` settings or remove the line to hide bank blips on the map.

#### 3. config.lua

This file contains general settings for the Banking Script.

```lua
return {
    reissueFee = 5000,
    atmDistance = 2.0,
    savingInterest = 2, --percent
    itemName = 'bank_card',
    managementJob = 'police', -- job needed to open management 
    progressBar = function()
        return lib.progressBar({
            duration = 3000,
            label = 'Showing Information..',
            useWhileDead = false,
            canCancel = true,
            disable = {
              car = true,
            },
            anim = {
              dict = "amb@prop_human_atm@male@enter",
              clip = "enter",
            },
          })
    end
}
```

Adjust these settings to customize the script's behavior:

* `reissueFee`: Cost to reissue a bank card
* `atmDistance`: Interaction distance for ATMs
* `savingInterest`: Interest rate for savings accounts
* `itemName`: Name of the bank card item in your inventory system
* `managementJob`: Job required to access management features
* `progressBar`: Function to display a progress bar (customize as needed)

### Server Exports

#### registerTransaction

```lua
registerTransaction(iban, amount, note, type, name)
```

🔹Parameters:

* `iban`: string - Account IBAN
* `amount`: number
* `note`: string
* `type`: string - 'deposit' | 'withdraw' | 'receive' | 'send'
* `name`: string

### addBalance

```lua
addBalance(iban, amount, data)
```

🔹Parameters:

* `iban`: string - Account IBAN
* `amount`: number
* `data`: table
  * `transaction`: boolean - Whether to register transaction
  * `note`: string - Transaction note (requires `transaction` to be true)
  * `removeCash`: boolean - If true, removes cash from player
  * `type:` string - 'deposit' | 'withdraw' | 'receive' | 'send     

### removeBalance

```lua
removeBalance(iban, amount, data)
```

🔹Parameters:

* `iban`: string - Account IBAN
* `amount`: number
* `data`: table
  * `transaction`: boolean - Whether to register transaction
  * `note`: string - Transaction note (requires `transaction` to be true)
  * `addCash`: boolean - If true, adds cash to player

### **Get Card Iban**

```lua
---@param owner number | string source or player cid
---@return string?
local iban = exports['nfs-banking']:getPlayerMainCardIban(owner)
```

### **Get Card Balance By IBAN**

```lua
---@param iban string
---@return number?
local balance = exports['nfs-banking']:getCardBalance(iban)
```

### **Get Card by IBAN**

```lua
---@param iban string
---@return nil | Card
local card = exports['nfs-banking']:getCardByIban(iban)
```

🔹Parameters:

* `main` (boolean)
* `balance` (number)
* `freeze` (boolean)
* `iban` (string)
* `day_stats` (`{income: number, expense: number}`)
* `quick_transfer_users` (`{iban: string, user_name: string}[]`)
* `overview` (`{day: string, amount: number}[]`)
* `pin` (number)
* `owner` (string)

### **Set Card New PIN**

```lua
---@param iban string
---@param newpin number
---@return boolean
local success = exports['nfs-banking']:setCardNewPin(iban, newpin)
```

### **Get Player Cards**

```lua
local cards = exports['nfs-banking']:getPlayerCards(source)
```

### **Freeze or Unfreeze Card**

```lua
exports['nfs-banking']:freezeCard(iban, true)

-- Example : 

local iban = exports['nfs-banking']:getPlayerMainCardIban(source)

if iban then
    if exports['nfs-banking']:freezeCard(iban, true) then
        print("✅ Card frozen!")
    end

    if exports['nfs-banking']:freezeCard(iban, false) then
        print("✅ Card unfrozen!")
    end
end
```

### Client Exports

### openBank

```lua
exports['nfs-banking']:openBank("bank")
```

Opens the banking interface.

### Events

#### Client Events

1. Card Action Event

Parameters:

data: { 

* amount: `number`,
* iban: `string`, 
* type: `string`, 
* note: `string`, 
* to\_iban: `string`

}

```lua
RegisterNetEvent('nfs-banking:client:cardAction', function(data)
    -- Your code here
end)
```

Triggered when a player makes a deposit/withdraw/transfer. `data` includes transaction details.

2. Hide Bank Event

```lua
AddEventHandler('n4s_banking:hideBank', function()
    -- Your code here
end)
```

Triggered when the player hides the bank interface.

3. Bank Opened Event

```lua
AddEventHandler('nfs-banking:client:bankOpened', function()
    -- Your code here
end)
```

Triggered when the player opens the banking interface.

#### Server Events

Bank Opened Event

```lua
RegisterNetEvent('nfs-banking:server:bankOpened', function()
    -- Your code here
end)
```

Triggered on the server when a player opens the banking interface.

### Bank Card Metadata

* iban `string` : unique IBAN for the card
* firstName `string` : player first name
* lastName `string` : player last name

### State Bag

You can check if the bank interface is open using the following state:

```lua
local isBankOpen = LocalPlayer.state.bankOpen
```

This state can be used to prevent other actions while the banking interface is open.

### Hooks 

#### `registerBankingHook`

This function allows developers to add custom logic to banking events.

**Parameters:**

* `hookType` (string): The type of hook (`deposit`, `withdraw`, `transfer`).
* `func` (function): Custom function to validate or modify the transaction.

**Payload:**

* `iban` (string): IBAN of the account.
* `amount` (number): Transaction amount.
* `note` (string): Transaction note.
* `to_iban` (string): Recipient's IBAN (for transfers).
* `owner` (string): Owner's identifier.

{% hint style="info" %}
Please do read the commented message regarding the 'return' .
{% endhint %}

```lua
exports['nfs-banking']:registerBankingHook('deposit', function(source, data)
    local playerCid = Framework.core.GetPlayer(source).id
    if playerCid ~= data.owner then
        return 'You are not allowed to deposit into this account.'
    end
    return true
end)

-- return: string | boolean | nil
-- only true will valid the transaction, while string will be the error text
```

### Integration Tips

1. Use the provided functions and events to integrate banking features into other scripts.
2. Customize the progress bar function in `config.lua` to match your server's UI style.
3. Adjust the `managementJob` in `config.lua` to fit your server's job system.
4. Modify ATM models and bank locations to match your server's map and assets.

Remember to restart your server after making changes to these configuration files.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://needforscript.gitbook.io/needforscripts/our-scripts/banking-script/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.