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

# Exports & events

Public API of Cuxial Banking: server exports to move money, pay salaries and charge cards, plus its events.

Move money, leave paychecks, charge cards and read accounts from your own resources. All exports run on the server.

```lua
exports.cuxial_banking:<Name>(...)
```

{% hint style="info" %}
Amounts are positive whole numbers. Decimals are cut off. Zero, negative, invalid or absurdly large values make the export return `false`.
{% endhint %}

## Player money

### AddMoney

Pays money to a character, online or offline.

```lua
exports.cuxial_banking:AddMoney(citizenId, amount, account)
```

| Parameter   | Type   | Description                                                      |
| ----------- | ------ | ---------------------------------------------------------------- |
| `citizenId` | string | Character identifier.                                            |
| `amount`    | number | Amount to add.                                                   |
| `account`   | string | `'bank'`, `'cash'` or `'crypto'`. Optional; `'bank'` by default. |

**Returns:** `boolean`.

```lua
exports.cuxial_banking:AddMoney(citizenId, 1500)
```

### RemoveMoney

Takes money from a character if they have enough.

```lua
exports.cuxial_banking:RemoveMoney(citizenId, amount, account)
```

Same parameters as `AddMoney`.

**Returns:** `boolean`. `false` when the balance is not enough.

```lua
if exports.cuxial_banking:RemoveMoney(citizenId, 250, 'bank') then
    -- paid
end
```

{% hint style="warning" %}
`AddMoney` and `RemoveMoney` write nothing to the history. Add the entry yourself with `AddTransaction`.
{% endhint %}

### GetAccount

Reads the money of a character who is online.

```lua
local account = exports.cuxial_banking:GetAccount(citizenId)
```

**Returns:** `{ citizenid, name, bank, cash }`, or `nil` when the character is not online.

```lua
local account = exports.cuxial_banking:GetAccount(citizenId)
if account and account.bank >= 5000 then
    -- can afford it
end
```

## History

### AddTransaction

Writes a movement to the history of an account.

```lua
exports.cuxial_banking:AddTransaction(identifier, transaction)
```

| Parameter                         | Type   | Description                                                                                                                   |
| --------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `identifier`                      | string | Character identifier, job name or shared account code.                                                                        |
| `transaction.value`               | number | Positive for money in, negative for money out.                                                                                |
| `transaction.reason`              | string | Text shown in the history. Up to 255 characters.                                                                              |
| `transaction.type`                | string | `'deposit'`, `'withdraw'`, `'transfer'`, `'loan'`, `'card'`, `'fee'` or `'interest'`. Anything else is stored as `'deposit'`. |
| `transaction.sender_name`         | string | Name of the sender.                                                                                                           |
| `transaction.sender_identifier`   | string | Identifier of the sender.                                                                                                     |
| `transaction.receiver_name`       | string | Name of the receiver.                                                                                                         |
| `transaction.receiver_identifier` | string | Identifier of the receiver.                                                                                                   |
| `transaction.date`                | string | `'YYYY-MM-DD HH:MM:SS'`. Optional; now by default.                                                                            |

**Returns:** `boolean`.

```lua
exports.cuxial_banking:AddTransaction(citizenId, {
    value = -250,
    reason = 'Parking fine',
    type = 'fee',
    sender_name = 'John Doe',
    sender_identifier = citizenId,
    receiver_name = 'City Hall',
    receiver_identifier = 'cityhall',
})
```

### GetPlayerTransactions

Returns the latest movements of an account.

```lua
local list = exports.cuxial_banking:GetPlayerTransactions(identifier)
```

**Returns:** `table[]`. Each entry has the fields of `AddTransaction`. The length is limited by `MaxTransactionsPerPlayer`.

```lua
for _, tx in ipairs(exports.cuxial_banking:GetPlayerTransactions(citizenId)) do
    print(tx.date, tx.value, tx.reason)
end
```

## Business accounts

The `society` parameter is the job name. The form `society_<job>` is accepted too.

### AddSocietyMoney

```lua
exports.cuxial_banking:AddSocietyMoney(society, amount, reason)
```

| Parameter | Type   | Description                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| `society` | string | Job name.                                                                    |
| `amount`  | number | Amount to add.                                                               |
| `reason`  | string | Optional. When given, the movement is written to the history of the account. |

**Returns:** `boolean`. `false` when the account does not exist.

```lua
exports.cuxial_banking:AddSocietyMoney('mechanic', 800, 'Repair invoice')
```

### RemoveSocietyMoney

```lua
exports.cuxial_banking:RemoveSocietyMoney(society, amount, reason)
```

Same parameters as `AddSocietyMoney`.

**Returns:** `boolean`. `false` when the account does not exist or the balance is not enough.

```lua
if exports.cuxial_banking:RemoveSocietyMoney('police', 500, 'Equipment') then
    -- paid from the business account
end
```

### GetSocietyAccount

```lua
local account = exports.cuxial_banking:GetSocietyAccount(society)
```

**Returns:** `{ society, society_name, balance, iban, credit_score, opening_date }`, or `nil` when the account does not exist.

```lua
local account = exports.cuxial_banking:GetSocietyAccount('police')
print(account and account.balance or 0)
```

## Paychecks

### AddPaycheck

Leaves a paycheck for a character to collect at a branch. This is how salaries reach the bank: it does not create them on its own.

```lua
exports.cuxial_banking:AddPaycheck(citizenId, sourceKey, sourceName, amount, status)
```

| Parameter    | Type   | Description                                               |
| ------------ | ------ | --------------------------------------------------------- |
| `citizenId`  | string | Character identifier.                                     |
| `sourceKey`  | string | Where it comes from, usually the job name.                |
| `sourceName` | string | Name shown to the player.                                 |
| `amount`     | number | Amount of the paycheck.                                   |
| `status`     | string | `'ready'` or `'pending'`. Optional; `'ready'` by default. |

**Returns:** `boolean`.

```lua
exports.cuxial_banking:AddPaycheck(citizenId, 'police', 'Police Department', 500)
```

## Cards

### ChargeCard

Charges a card the player is carrying. Use it for card payments in shops.

```lua
local result = exports.cuxial_banking:ChargeCard(source, cardNumber, pin, amount, reason)
```

| Parameter    | Type             | Description                                                                           |
| ------------ | ---------------- | ------------------------------------------------------------------------------------- |
| `source`     | number           | Server id of the player who pays. They must carry the card.                           |
| `cardNumber` | string           | Number of the card.                                                                   |
| `pin`        | string \| number | PIN typed by the player.                                                              |
| `amount`     | number           | Amount to charge. Limited by `cards.posMaxCharge` and by the daily limit of the card. |
| `reason`     | string           | Name of the merchant, shown in the history. Optional.                                 |

**Returns:** `{ success, message, cardHolder, last4 }`. `message` is only set on failure; `cardHolder` and `last4` only on success.

```lua
local result = exports.cuxial_banking:ChargeCard(source, cardNumber, pin, 120, 'Supermarket')
if not result.success then
    print(result.message)
end
```

### RefundCard

Returns a charge to the owner of the card.

```lua
exports.cuxial_banking:RefundCard(cardNumber, amount, reason)
```

**Returns:** `boolean`. The money always goes to the owner of the card, never to whoever paid with it.

```lua
exports.cuxial_banking:RefundCard(cardNumber, 120, 'Supermarket')
```

### GetPlayerCards

Lists the cards a player is carrying.

```lua
local cards = exports.cuxial_banking:GetPlayerCards(source)
```

**Returns:** `table[]`. Each entry has `cardNumber`, `cardHolder`, `cardHolderCitizenId`, `cardHolderIBAN`, `cardType`, `cardTypeLabel`, `dailyLimit`, `accountType`, `status`, `expiryDate`, `slot` and `item`.

```lua
for _, card in ipairs(exports.cuxial_banking:GetPlayerCards(source)) do
    if card.status == 'active' then
        -- offer it as a payment method
    end
end
```

## Settings

### getSetting

Reads a section of the live settings, as it is in use right now.

```lua
local cards = exports.cuxial_banking:getSetting('config.cards')
```

| Parameter | Type   | Description                                                                                                                                                                                                           |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string | `'config.general'`, `'config.accounts'`, `'config.cards'`, `'config.loans'`, `'config.savings'`, `'config.cheques'`, `'config.rewards'`, `'config.creditScore'`, `'config.atm'`, `'config.admin'` or `'config.logs'`. |

**Returns:** `table`, or `nil` for an unknown section.

```lua
local general = exports.cuxial_banking:getSetting('config.general')
print(general.currency)
```

## Wealth report

The Citizens tab of the staff panel adds up everything a character owns. Your resource can add its own lines.

### RegisterWealthProvider

```lua
exports.cuxial_banking:RegisterWealthProvider(name, fn)
```

| Parameter | Type     | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `name`    | string   | Unique name of the source.                                     |
| `fn`      | function | Receives the character identifier and returns a list of lines. |

Each line:

| Field    | Type   | Description                                                                                                                                                                                                |
| -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`    | string | Identifier of the line.                                                                                                                                                                                    |
| `label`  | string | Text shown in the panel.                                                                                                                                                                                   |
| `amount` | number | Value. Lines with zero are dropped.                                                                                                                                                                        |
| `kind`   | string | `'asset'` adds to the net worth. `'transit'` adds too: money on its way. `'liability'` subtracts. `'control'` is shown without adding: funds the character manages but does not own. `'asset'` by default. |
| `detail` | table  | Optional. Extra text, number or boolean values.                                                                                                                                                            |

**Returns:** `boolean`. `false` when another resource already registered that name.

```lua
exports.cuxial_banking:RegisterWealthProvider('myshop', function(citizenId)
    return {
        { key = 'till', label = 'Shop till', amount = 3200, kind = 'asset' },
    }
end)
```

The source is removed by itself when your resource stops.

### UnregisterWealthProvider

```lua
exports.cuxial_banking:UnregisterWealthProvider(name)
```

**Returns:** `boolean`. Only the resource that registered a source can remove it.

## Events

### cuxial\_banking:client:OpenAtm

Client event. Opens the ATM for the local player from your own resource, for example from a custom ATM prop.

| Parameter | Type    | Description                                                           |
| --------- | ------- | --------------------------------------------------------------------- |
| `coords`  | vector3 | Position of the ATM. Optional; the position of the player by default. |

```lua
TriggerEvent('cuxial_banking:client:OpenAtm', GetEntityCoords(atmEntity))
```

The player still needs an active card and its PIN, and must stay within `atmDistance` of those coordinates.

### cuxial\_banking:settingsApplied

Local event, on the server and on each client. Triggered when a settings section is loaded or changed from the staff panel.

| Parameter | Type   | Description                                         |
| --------- | ------ | --------------------------------------------------- |
| `id`      | string | Section that changed, for example `'config.cards'`. |

```lua
-- server side
AddEventHandler('cuxial_banking:settingsApplied', function(id)
    if id == 'config.cards' then
        local cards = exports.cuxial_banking:getSetting('config.cards')
    end
end)
```


---

# 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://docs.cuxial.com/scripts/core/cuxial-banking/developers.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.