> For the complete documentation index, see [llms.txt](https://dragon-heart-studios.gitbook.io/dragonheartstudios/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dragon-heart-studios.gitbook.io/dragonheartstudios/scripts/dhs-bankingsim/exports-and-commands.md).

# Exports and Commands

All server exports are called via:

```lua
exports['DHS-BankingSim']:ExportName(...)
```

Client exports follow the same pattern from client-side scripts.

***

### Money Operations

#### GetPlayerBalance

Returns a player's balance for a given account type.

```lua
local balance = exports['DHS-BankingSim']:GetPlayerBalance(source, accountType)
```

| Parameter     | Type   | Required | Description                                                                             |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `source`      | number | Yes      | Player server ID                                                                        |
| `accountType` | string | No       | `'checking'` (default), `'savings'`, `'crypto'`, `'business'`, `'joint'`, or `'escrow'` |

**Returns:** `number` or `nil`

```lua
-- Example: get checking balance
local checking = exports['DHS-BankingSim']:GetPlayerBalance(source, 'checking')

-- Example: get savings balance
local savings = exports['DHS-BankingSim']:GetPlayerBalance(source, 'savings')
```

***

#### AddMoney

Adds money to a player's account.

```lua
local result = exports['DHS-BankingSim']:AddMoney(source, accountType, amount, reason, logTransaction)
```

| Parameter        | Type    | Required | Description                                                                             |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `source`         | number  | Yes      | Player server ID                                                                        |
| `accountType`    | string  | No       | `'checking'` (default), `'savings'`, `'crypto'`, `'business'`, `'joint'`, or `'escrow'` |
| `amount`         | number  | Yes      | Amount to add (must be positive)                                                        |
| `reason`         | string  | No       | Description for the transaction                                                         |
| `logTransaction` | boolean | No       | If `true`, creates a ledger entry visible in banking UI                                 |

**Returns:** `{ success: boolean, newBalance: number, message: string }`

```lua
-- Example: pay a player for a job
local result = exports['DHS-BankingSim']:AddMoney(source, 'checking', 500, 'Fishing job payout', true)
if result.success then
    print('New balance: $' .. result.newBalance)
end
```

***

#### RemoveMoney

Removes money from a player's account. Respects overdraft limits and frozen account status.

```lua
local result = exports['DHS-BankingSim']:RemoveMoney(source, accountType, amount, reason, logTransaction)
```

| Parameter        | Type    | Required | Description                                                                             |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `source`         | number  | Yes      | Player server ID                                                                        |
| `accountType`    | string  | No       | `'checking'` (default), `'savings'`, `'crypto'`, `'business'`, `'joint'`, or `'escrow'` |
| `amount`         | number  | Yes      | Amount to remove (must be positive)                                                     |
| `reason`         | string  | No       | Description for the transaction                                                         |
| `logTransaction` | boolean | No       | If `true`, creates a ledger entry visible in banking UI                                 |

**Returns:** `{ success: boolean, newBalance: number, message: string }`

```lua
-- Example: charge a player for a vehicle repair
local result = exports['DHS-BankingSim']:RemoveMoney(source, 'checking', 1200, 'Vehicle repair', true)
if not result.success then
    -- result.message will explain why (e.g. "Insufficient funds")
end
```

***

#### TransferMoney

Transfers money between two players' checking accounts. Works even if the recipient is offline.

```lua
local result = exports['DHS-BankingSim']:TransferMoney(fromSource, toCitizenId, amount, reason, logTransaction)
```

| Parameter        | Type    | Required | Description                                        |
| ---------------- | ------- | -------- | -------------------------------------------------- |
| `fromSource`     | number  | Yes      | Sender's server ID                                 |
| `toCitizenId`    | string  | Yes      | Recipient's citizen ID                             |
| `amount`         | number  | Yes      | Amount to transfer                                 |
| `reason`         | string  | No       | Description for the transaction                    |
| `logTransaction` | boolean | No       | If `true`, creates ledger entries for both parties |

**Returns:** `{ success: boolean, message: string }`

```lua
-- Example: court-ordered restitution payment
local result = exports['DHS-BankingSim']:TransferMoney(source, 'ABC12345', 5000, 'Court restitution', true)
```

***

### Account & Card Queries

#### GetPlayerAccounts

Returns all bank accounts for a citizen ID. Works for offline players.

```lua
local accounts = exports['DHS-BankingSim']:GetPlayerAccounts(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `table[]` — Array of account records (`id`, `citizenid`, `account_number`, `account_type`, `balance`, `frozen`, etc.)

***

#### GetPlayerCards

Returns all bank cards for a citizen ID. Works for offline players.

```lua
local cards = exports['DHS-BankingSim']:GetPlayerCards(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `table[]` — Array of card records (`id`, `citizenid`, `card_type`, `last_four`, `status`, etc.)

***

#### HasValidCard

Checks if a player has at least one active card on a non-frozen account.

```lua
local hasCard = exports['DHS-BankingSim']:HasValidCard(source)
```

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `source`  | number | Yes      | Player server ID |

**Returns:** `boolean`

```lua
-- Example: require a bank card before allowing a purchase
if not exports['DHS-BankingSim']:HasValidCard(source) then
    TriggerClientEvent('ox_lib:notify', source, { description = 'You need a bank card', type = 'error' })
    return
end
```

***

#### IsAccountFrozen

Checks if a specific account is frozen.

```lua
local frozen = exports['DHS-BankingSim']:IsAccountFrozen(accountId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `accountId` | number | Yes      | Account database ID |

**Returns:** `boolean`

***

### Billing & Invoicing

#### CreateBill

Creates a bill for a player (e.g. utility bills, fines, rent).

```lua
local result = exports['DHS-BankingSim']:CreateBill(citizenId, amount, reason, dueDate, sourceScript)
```

| Parameter      | Type   | Required | Description                                                      |
| -------------- | ------ | -------- | ---------------------------------------------------------------- |
| `citizenId`    | string | Yes      | Target player's citizen ID                                       |
| `amount`       | number | Yes      | Bill amount                                                      |
| `reason`       | string | No       | Bill description                                                 |
| `dueDate`      | string | No       | Due date as `'YYYY-MM-DD HH:MM:SS'`. Defaults to 7 days from now |
| `sourceScript` | string | No       | Invoking resource name (auto-detected if omitted)                |

**Returns:** `{ success: boolean, billId: number, billNumber: string, message: string }`

```lua
-- Example: housing rent bill
local result = exports['DHS-BankingSim']:CreateBill('ABC12345', 2500, 'Monthly rent - 4 Alta St', '2026-05-01 00:00:00')
```

***

#### CreateInvoice

Creates an itemized invoice with optional tax calculation.

```lua
local result = exports['DHS-BankingSim']:CreateInvoice(businessId, citizenId, items, taxRate, sourceScript)
```

| Parameter      | Type     | Required | Description                                             |
| -------------- | -------- | -------- | ------------------------------------------------------- |
| `businessId`   | number   | No       | Business account ID (for record-keeping)                |
| `citizenId`    | string   | Yes      | Target player's citizen ID                              |
| `items`        | table\[] | Yes      | Array of `{ name: string, qty: number, price: number }` |
| `taxRate`      | number   | No       | Tax percentage (e.g. `8.5` for 8.5%). Default `0`       |
| `sourceScript` | string   | No       | Auto-detected if omitted                                |

**Returns:** `{ success: boolean, invoiceId: number, billNumber: string, amount: number, message: string }`

```lua
-- Example: mechanic shop invoice
local result = exports['DHS-BankingSim']:CreateInvoice(nil, 'ABC12345', {
    { name = 'Oil Change', qty = 1, price = 150 },
    { name = 'Brake Pads', qty = 4, price = 75 },
}, 8.5)
```

***

#### PayBillExternal

Programmatically pays a bill on behalf of a player (auto-pay, court-ordered, etc.).

```lua
local result = exports['DHS-BankingSim']:PayBillExternal(billId, payerSource)
```

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `billId`      | number | Yes      | Bill database ID              |
| `payerSource` | number | Yes      | Player server ID of the payer |

**Returns:** `{ success: boolean, message: string }`

***

#### GetPlayerBills

Returns all bills for a citizen ID.

```lua
local bills = exports['DHS-BankingSim']:GetPlayerBills(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `table[]` — Array of bill records

***

### Loans & Credit

#### GetCreditScore

Returns a player's credit score. Creates a default record (650) if none exists.

```lua
local score = exports['DHS-BankingSim']:GetCreditScore(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `number` (300–850) or `nil`

***

#### HasActiveLoan

Checks if a player has any active loan, optionally filtered by type.

```lua
local hasLoan = exports['DHS-BankingSim']:HasActiveLoan(citizenId, loanType)
```

| Parameter   | Type   | Required | Description                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
| `citizenId` | string | Yes      | Player's citizen ID                                                 |
| `loanType`  | string | No       | Filter: `'personal'`, `'vehicle'`, `'property'`, `'external'`, etc. |

**Returns:** `boolean`

```lua
-- Example: block a second vehicle loan
if exports['DHS-BankingSim']:HasActiveLoan(citizenId, 'vehicle') then
    -- player already has a vehicle loan
end
```

***

#### GetPlayerLoans

Returns all loan records for a citizen ID.

```lua
local loans = exports['DHS-BankingSim']:GetPlayerLoans(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `table[]` — Array of loan records (`id`, `loan_id`, `loan_type`, `principal_amount`, `remaining_balance`, `status`, etc.)

***

#### CreateExternalLoan

Creates a loan from an external source (vehicle dealer, property sale, etc.).

```lua
local result = exports['DHS-BankingSim']:CreateExternalLoan(citizenId, amount, loanType, interestRate, termMonths, reason)
```

| Parameter      | Type   | Required | Description                                                     |
| -------------- | ------ | -------- | --------------------------------------------------------------- |
| `citizenId`    | string | Yes      | Borrower's citizen ID                                           |
| `amount`       | number | Yes      | Loan principal                                                  |
| `loanType`     | string | No       | `'vehicle'`, `'property'`, `'personal'`, `'external'` (default) |
| `interestRate` | number | No       | Annual rate as decimal (e.g. `0.08` for 8%). Default `0.05`     |
| `termMonths`   | number | No       | Loan term in months. Default `12`                               |
| `reason`       | string | No       | Description                                                     |

**Returns:** `{ success: boolean, loanId: string, monthlyPayment: number, message: string }`

```lua
-- Example: vehicle dealer financing
local result = exports['DHS-BankingSim']:CreateExternalLoan(
    'ABC12345', 45000, 'vehicle', 0.065, 36, 'Vehicle purchase - Bravado Gauntlet'
)
if result.success then
    print('Loan ID: ' .. result.loanId .. ' | Monthly: $' .. string.format('%.2f', result.monthlyPayment))
end
```

***

### Fraud & Compliance

#### IsOnWatchlist

Checks if a player is on the fraud watchlist.

```lua
local watched = exports['DHS-BankingSim']:IsOnWatchlist(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `boolean`

***

#### IsIdentityFrozen

Checks if a player's entire banking identity is frozen.

```lua
local frozen = exports['DHS-BankingSim']:IsIdentityFrozen(citizenId)
```

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `citizenId` | string | Yes      | Player's citizen ID |

**Returns:** `boolean`

```lua
-- Example: block a transaction if frozen
if exports['DHS-BankingSim']:IsIdentityFrozen(citizenId) then
    -- player's banking is frozen, block the action
end
```

***

#### GetTransactionHistory

Returns recent transactions for a citizen ID.

```lua
local transactions = exports['DHS-BankingSim']:GetTransactionHistory(citizenId, limit)
```

| Parameter   | Type   | Required | Description                                    |
| ----------- | ------ | -------- | ---------------------------------------------- |
| `citizenId` | string | Yes      | Player's citizen ID                            |
| `limit`     | number | No       | Max records to return. Default `50`, max `500` |

**Returns:** `table[]` — Ordered by most recent first

***

#### FreezePlayerBanking

Freezes a player's entire banking identity. Intended for law enforcement / DOJ scripts.

```lua
local result = exports['DHS-BankingSim']:FreezePlayerBanking(citizenId, reason, authority)
```

| Parameter   | Type   | Required | Description                                                       |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| `citizenId` | string | Yes      | Target player's citizen ID                                        |
| `reason`    | string | No       | Reason for the freeze                                             |
| `authority` | string | No       | Who ordered it (e.g. `'LSPD'`, `'DOJ'`). Auto-detected if omitted |

**Returns:** `{ success: boolean, message: string }`

```lua
-- Example: police MDT freeze
exports['DHS-BankingSim']:FreezePlayerBanking('ABC12345', 'Suspected money laundering', 'LSPD')
```

***

### POS & Merchant

#### ProcessExternalPayment

Processes a real POS payment that appears in the merchant's transaction history.

```lua
local result = exports['DHS-BankingSim']:ProcessExternalPayment(merchantId, customerSource, amount, items, description)
```

| Parameter        | Type   | Required | Description                        |
| ---------------- | ------ | -------- | ---------------------------------- |
| `merchantId`     | number | Yes      | Merchant database ID               |
| `customerSource` | number | Yes      | Customer's server ID               |
| `amount`         | number | Yes      | Payment amount                     |
| `items`          | table  | No       | Array of item data for the receipt |
| `description`    | string | No       | Payment description                |

**Returns:** `{ success: boolean, transactionId: string, message: string }`

```lua
-- Example: shop script charges customer through POS
local result = exports['DHS-BankingSim']:ProcessExternalPayment(merchantId, source, 350, {
    { name = 'Repair Kit', qty = 2, price = 175 },
}, 'Vehicle parts purchase')
```

***

#### GetMerchantByBusiness

Returns the merchant record linked to a business ID.

```lua
local merchant = exports['DHS-BankingSim']:GetMerchantByBusiness(businessId)
```

| Parameter    | Type   | Required | Description         |
| ------------ | ------ | -------- | ------------------- |
| `businessId` | number | Yes      | Business account ID |

**Returns:** `table` or `nil`

***

#### IsMerchantRegistered

Checks whether a business has a registered POS merchant.

```lua
local registered = exports['DHS-BankingSim']:IsMerchantRegistered(businessId)
```

| Parameter    | Type   | Required | Description         |
| ------------ | ------ | -------- | ------------------- |
| `businessId` | number | Yes      | Business account ID |

**Returns:** `boolean`

***

#### GetMerchantBalance

Returns a merchant's settled and pending balances.

```lua
local balances = exports['DHS-BankingSim']:GetMerchantBalance(merchantId)
```

| Parameter    | Type   | Required | Description          |
| ------------ | ------ | -------- | -------------------- |
| `merchantId` | number | Yes      | Merchant database ID |

**Returns:** `{ settledBalance: number, pendingBalance: number }` or `nil`

***

### Documents

#### GenerateProofOfFunds

Generates an official proof-of-funds document for a player.

```lua
local result = exports['DHS-BankingSim']:GenerateProofOfFunds(citizenId, amount)
```

| Parameter   | Type   | Required | Description             |
| ----------- | ------ | -------- | ----------------------- |
| `citizenId` | string | Yes      | Player's citizen ID     |
| `amount`    | number | No       | Reserved for future use |

**Returns:** `{ success: boolean, documentId: string, documentData: table, message: string }`

***

#### GenerateAccountStatement

Generates an account statement for a specified period.

```lua
local result = exports['DHS-BankingSim']:GenerateAccountStatement(citizenId, accountId, periodDays)
```

| Parameter    | Type   | Required | Description                            |
| ------------ | ------ | -------- | -------------------------------------- |
| `citizenId`  | string | Yes      | Player's citizen ID                    |
| `accountId`  | number | Yes      | Account database ID                    |
| `periodDays` | number | No       | Statement period in days. Default `30` |

**Returns:** `{ success: boolean, documentId: string, documentData: table, message: string }`

***

#### VerifyDocument

Verifies whether a banking document is valid and not expired.

```lua
local result = exports['DHS-BankingSim']:VerifyDocument(documentId)
```

| Parameter    | Type   | Required | Description                           |
| ------------ | ------ | -------- | ------------------------------------- |
| `documentId` | string | Yes      | The document ID (e.g. `'DOC-A1B2C3'`) |

**Returns:** `{ success: boolean, valid: boolean, documentData: table, message: string }`

```lua
-- Example: verify a certified check before accepting
local result = exports['DHS-BankingSim']:VerifyDocument('DOC-A1B2C3')
if result.valid then
    print('Document is authentic and current')
else
    print('Invalid or expired: ' .. result.message)
end
```

***

#### IssueCertifiedCheck

Issues a certified (guaranteed) bank check from one player to another. Deducts funds immediately.

```lua
local result = exports['DHS-BankingSim']:IssueCertifiedCheck(fromCitizenId, toCitizenId, amount, memo)
```

| Parameter       | Type   | Required | Description                         |
| --------------- | ------ | -------- | ----------------------------------- |
| `fromCitizenId` | string | Yes      | Payer's citizen ID (must be online) |
| `toCitizenId`   | string | Yes      | Recipient's citizen ID              |
| `amount`        | number | Yes      | Check amount                        |
| `memo`          | string | No       | Memo / description                  |

**Returns:** `{ success: boolean, checkId: string, checkNumber: string, message: string }`

```lua
-- Example: issue a certified check for a property sale
local result = exports['DHS-BankingSim']:IssueCertifiedCheck('ABC12345', 'XYZ67890', 150000, 'Property sale - 4 Alta St')
```

***

### Employee & Business

#### IsBankEmployee

Checks if a player is an active bank employee.

```lua
local isEmployee = exports['DHS-BankingSim']:IsBankEmployee(source, bankId)
```

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `source`  | number | Yes      | Player server ID                            |
| `bankId`  | number | No       | Specific bank ID. If `nil`, checks any bank |

**Returns:** `boolean`

***

#### GetEmployeeRole

Returns the bank role for a player.

```lua
local role = exports['DHS-BankingSim']:GetEmployeeRole(source, bankId)
```

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `source`  | number | Yes      | Player server ID                            |
| `bankId`  | number | No       | Specific bank ID. If `nil`, checks any bank |

**Returns:** `string` or `nil` — One of: `'teller'`, `'loan_officer'`, `'vault_manager'`, `'compliance'`, `'manager'`, `'owner'`

```lua
-- Example: check if player is a manager or higher
local role = exports['DHS-BankingSim']:GetEmployeeRole(source)
if role == 'manager' or role == 'owner' then
    -- allow management action
end
```

***

#### GetBusinessBalance

Returns the balance of a business account.

```lua
local balance = exports['DHS-BankingSim']:GetBusinessBalance(businessId)
```

| Parameter    | Type   | Required | Description         |
| ------------ | ------ | -------- | ------------------- |
| `businessId` | number | Yes      | Business account ID |

**Returns:** `number` or `nil`

***

#### IsOnDuty

Checks whether a bank employee is currently clocked in.

```lua
local onDuty = exports['DHS-BankingSim']:IsOnDuty(source)
```

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `source`  | number | Yes      | Player server ID |

**Returns:** `boolean`

***

### Client Exports

These are called from **client-side** scripts only.

#### GetPlayerBankData

Returns cached banking data from the last server fetch (accounts, cards, balances). Returns `nil` if data hasn't loaded yet.

```lua
local data = exports['DHS-BankingSim']:GetPlayerBankData()
```

**Returns:** `table` or `nil` — Contains `accounts`, `cards`, `cash`, `bank`, etc.

***

#### OpenPhoneBanking

Opens the phone banking UI programmatically.

```lua
exports['DHS-BankingSim']:OpenPhoneBanking()
```

***

#### HasBankCard

Quick client-side check from cached data for whether the player has an active bank card.

```lua
local hasCard = exports['DHS-BankingSim']:HasBankCard()
```

**Returns:** `boolean`

***

### Notes

* All server exports that modify money accept an optional `logTransaction` boolean. When `true`, the transaction appears in the player's banking UI history.
* Exports that take a `source` parameter require the player to be online.
* Exports that take a `citizenId` (identifier) parameter work for both online and offline players.
* All money-mutating exports automatically tag the calling resource via `GetInvokingResource()` for audit purposes.
* Frozen accounts will block debit operations — the `message` field in the return table will explain why.
* The `logTransaction` parameter defaults to `false` to avoid cluttering the ledger with internal operations. Set it to `true` for player-visible transactions.