Developers

Every account export takes an account id:

Whether a player is connected makes no difference to a personal account: it reads and moves the same either way. PayBill is the one export that needs the player online, and only for a bill sent to a player.

A few rules hold for every export:

• The account exports wait until the bank has loaded its accounts before answering, so a resource that starts beside the bank gets real answers, not misses.
• Amounts are whole numbers. Decimals are rounded down, and an amount of zero or less, or above 2000000000, is refused.
• Exports skip the checks made for players: transfer limits, the offline-transfer setting, the billing list, the limit of 10 open bills on one account and Hooks.canTransact apply only to what players do in the bank. The Bills and Requests switches do apply: CreateBill and PayBill refuse while they are off.
• The money exports return a refusal code as their third value when they refuse.
• Money an export moves is written into the history, naming the calling resource as the actor (PayBill names the player), and fires lation_banking:transaction.

Server exportsCopy Anchor Link

AccountsCopy Anchor Link

GetAccountCopy Anchor Link

local account = exports.lation_banking:GetAccount(id)

The account:

{
    id = 'police',
    type = 'society',          -- 'personal', 'savings', 'shared', 'society' or 'business'
    name = 'LSPD',             -- the display name
    number = 'LS88001000',     -- the account number, without spaces
    balance = 18325,
    owner = nil,               -- the owner's identifier; the player's own for a personal account
    frozen = false,            -- frozen by an admin
    members = {
        { identifier = 'ABC12345', name = 'Jane Doe', permissions = { deposit = true, withdraw = true, transfer = true, manage = false } },
    },
}

GetAccountBalanceCopy Anchor Link

local balance = exports.lation_banking:GetAccountBalance(id)

local balance = exports.lation_banking:GetAccountBalance('police') or 0

GetPlayerAccountsCopy Anchor Link

local accounts = exports.lation_banking:GetPlayerAccounts(identifier)

Each entry has the GetAccount fields plus role (owner, member or boss) and, while the player is online, permissions. For an offline player, a society reached through their job or gang can't be seen; a society they were added to by name still shows.

GetAccountMembersCopy Anchor Link

local members = exports.lation_banking:GetAccountMembers(id)

GetPlayerAccountNumberCopy Anchor Link

local number = exports.lation_banking:GetPlayerAccountNumber(identifier)

GetIdentifierByAccountNumberCopy Anchor Link

local identifier = exports.lation_banking:GetIdentifierByAccountNumber(number)

local identifier = exports.lation_banking:GetIdentifierByAccountNumber('LS 1234 5678')

MoneyCopy Anchor Link

Refusal codesCopy Anchor Link

AddAccountMoney, RemoveAccountMoney, TransferMoney and PayBill return false and a code as their third value when they refuse. The second value stays what it always was, so scripts that read it keep working; test the third. A code is the last part of the bank's errors.<code> locale key where there is one, and is never translated.

local ok, message, code = exports.lation_banking:TransferMoney('police', 'LS12345678', 1000, 'Consulting')
if not ok and code == 'insufficient_funds' then
    -- the police account is short
end

AddAccountMoneyCopy Anchor Link

local ok, _, code = exports.lation_banking:AddAccountMoney(id, amount, note)

Credits the account and writes an income line. On a personal account it moves the framework's bank money, online or not. A frozen account still takes money in.

exports.lation_banking:AddAccountMoney('police', 2500, 'Impound fee')

RemoveAccountMoneyCopy Anchor Link

local ok, _, code = exports.lation_banking:RemoveAccountMoney(id, amount, note)

Debits the account and writes an expense line.

local ok, _, code = exports.lation_banking:RemoveAccountMoney('mechanic', 900, 'Parts order')
if not ok then
    return -- 'insufficient_funds': the society can't pay for it; 'frozen': an admin froze it
end

TransferMoneyCopy Anchor Link

local ok, message, code = exports.lation_banking:TransferMoney(fromId, toId, amount, note)

Moves the money and writes a transfer_out and a transfer_in line under one reference, and tells an online player who received it. Offline recipients are always paid.

On failure the message is invalid, recipient_unknown or same_account when the call is refused before anything is looked up, and the bank's own message in the server's language after that (a frozen sender reads as insufficient funds there). The code says which it was: insufficient_funds, frozen, unknown_account, failed and the rest in the table.

local ok, message, code = exports.lation_banking:TransferMoney('police', 'LS12345678', 1000, 'Consulting')
if not ok then print(('transfer refused: %s (%s)'):format(code, message)) end

Managing accountsCopy Anchor Link

CreateAccountCopy Anchor Link

local account, err = exports.lation_banking:CreateAccount(data)

A player may hold one savings account. The shared-account limit per player doesn't apply here, and business accounts never count against it.

local account, err = exports.lation_banking:CreateAccount({ id = 'myshop:12', type = 'business', name = 'Bean Machine', owner = ownerIdentifier })
if not account then print(('could not open the account: %s'):format(err)) end

DeleteAccountCopy Anchor Link

local ok = exports.lation_banking:DeleteAccount(id)

Removes the account and its members.

RenameAccountCopy Anchor Link

local ok = exports.lation_banking:RenameAccount(id, name)

The id never changes. A society's name is set back to its job's label on the next start.

SetAccountFrozenCopy Anchor Link

local ok = exports.lation_banking:SetAccountFrozen(id, frozen)

A frozen account takes money in but refuses withdrawals, transfers out and bill payments.

SetAccountOwnerCopy Anchor Link

local ok = exports.lation_banking:SetAccountOwner(id, identifier)

A member who becomes the owner stops being a member.

AddAccountMemberCopy Anchor Link

local ok = exports.lation_banking:AddAccountMember(id, identifier, permissions)

manage only means something on a shared account; on society and business accounts members never manage. A player added to a society who isn't one of its bosses uses these permissions.

exports.lation_banking:AddAccountMember('police', identifier, { deposit = true, withdraw = false, transfer = false })

UpdateAccountMemberCopy Anchor Link

local ok = exports.lation_banking:UpdateAccountMember(id, identifier, permissions)

RemoveAccountMemberCopy Anchor Link

local ok = exports.lation_banking:RemoveAccountMember(id, identifier)

ClearAccountMembersCopy Anchor Link

local ok = exports.lation_banking:ClearAccountMembers(id)

Removes every member at once, for a business whose staff were all let go.

HistoryCopy Anchor Link

AddTransactionCopy Anchor Link

local ok = exports.lation_banking:AddTransaction(id, data)

Writes a history line without moving money, for a script that moves the money itself and wants a clear line in the history. When framework tracking already wrote the same move on a personal account in the last 5 seconds (same amount, same direction), that line is filled in instead of a second one being added.

-- the money already left through the framework; give the line its reason
exports.lation_banking:AddTransaction(identifier, { type = 'expense', amount = 400, note = 'Rent · Alta Street 12', counterparty = 'Alta Street Realty' })

GetTransactionsCopy Anchor Link

local page = exports.lation_banking:GetTransactions(id, options)

The page:

{
    transactions = {           -- newest first
        {
            id = 4512,
            type = 'income',
            amount = 2500,
            balanceAfter = 18325,
            note = 'Impound fee',
            counterparty = nil,
            counterpartyAccount = nil, -- formatted, 'LS 1234 5678'
            actor = 'my_impound',      -- the player, or the resource that called an export
            reference = nil,
            createdAt = 1730000000,    -- unix seconds
        },
    },
    pagination = { page = 1, perPage = 25, total = 120, totalPages = 5 },
    summary = { income = 52000, expense = 31000, net = 21000 }, -- across every matching row
}

local page = exports.lation_banking:GetTransactions('police', {
    perPage = 10,
    filters = { types = { 'income' }, dateFrom = os.date('%Y-%m-%d', os.time() - 7 * 86400) }
})
print(('police took in %d this week'):format(page.summary.income))

BillsCopy Anchor Link

CreateBillCopy Anchor Link

local billId, err = exports.lation_banking:CreateBill(data)

A bill from this export needs no society on the billing list and carries no employee cut. While Config > Bills > Bills is off it is refused with bills_disabled, since nobody could see or pay it.

• Sent to a player, they are told when it arrives and can decline it only while Players can decline bills is on.
• Sent to an account (business to business), everyone who may send money from that account sees it under the account's name and pays it from that account. It can always be declined and is never collected automatically. same_account means target and account are the same account.

-- a fine for a player
local billId, err = exports.lation_banking:CreateBill({ target = citizenid, amount = 1500, note = 'Speeding', account = 'police' })

-- one business billing another: the mechanics bill the police for a fleet service
local billId, err = exports.lation_banking:CreateBill({ target = 'police', amount = 3200, note = 'Fleet service', account = 'mechanic' })

PayBillCopy Anchor Link

local ok, reason = exports.lation_banking:PayBill(id, accountId)

Pays an unpaid bill.

• A player's bill is paid on their behalf, from accountId or their personal account. The player must be online.
• A bill sent to an account is paid from that account, with nobody online.

The message is a code for a refusal made before paying is tried (bill_settled, bills_disabled, requests_disabled, no_access, frozen, recipient_offline or busy) and the bank's own message after that; the third value is always the code.

-- the police pay the fleet service they were billed
local ok, message, code = exports.lation_banking:PayBill(billId)
if not ok and code == 'insufficient_funds' then print('the police account is short') end

CancelBillCopy Anchor Link

local ok = exports.lation_banking:CancelBill(id)

Cancels an unpaid bill. Nothing is collected, and when it belongs to a repeating series, the series ends.

GetBillsCopy Anchor Link

local bills = exports.lation_banking:GetBills(id, status)

A bill:

{
    id = 812,
    kind = 'bill',          -- 'bill' or 'request'
    amount = 1500,
    note = 'Speeding',
    status = 'unpaid',
    reference = '3FA9C2D1-0B7E',
    issuer = 'LSPD',        -- the name on the bill
    issuerId = nil,         -- the player who wrote it
    accountId = 'police',   -- where the money goes; nil for a fine
    target = 'ABC12345',    -- who pays: a player's identifier, or an account id
    createdAt = 1730000000,
    dueAt = 1730604800,
    paidAt = nil,
    commission = 0,         -- the employee cut, in percent
    sale = nil,             -- a register's ticket: { lines, subtotal, tax, taxRate, taxAccount?, note? }
    scheduleId = nil,       -- the repeating series it belongs to
    repeatDays = nil,
}

LoansCopy Anchor Link

GetLoanCopy Anchor Link

local loan = exports.lation_banking:GetLoan(identifier)

{
    id = 31,
    identifier = 'ABC12345',
    name = 'Jane Doe',
    principal = 10000,     -- borrowed
    interest = 10,         -- percent
    total = 11000,         -- to repay
    remaining = 7856,
    paid = 3144,
    installment = 1572,    -- per day
    termDays = 7,
    nextDue = 1730086400,  -- unix seconds
    missed = 0,
    status = 'active',     -- 'active' or 'defaulted'
    createdAt = 1729900000,
    closedAt = nil,
}

RegisterCopy Anchor Link

GetPosProductsCopy Anchor Link

local products = exports.lation_banking:GetPosProducts(accountId)

AddPosProductCopy Anchor Link

local productId, err = exports.lation_banking:AddPosProduct(accountId, data)

A register only sells from the menu of a society listed under Config > POS > Businesses. Open registers refresh at once.

exports.lation_banking:AddPosProduct('burgershot', { label = 'Bleeder', price = 12, category = 'Burgers', item = 'burger' })

RemovePosProductCopy Anchor Link

local ok = exports.lation_banking:RemovePosProduct(id)

Societies and registersCopy Anchor Link

For a resource that runs jobs or businesses of its own, such as lation jobs: society accounts on demand, and register entries under Config > POS that it keeps itself.

EnsureSocietyAccountsCopy Anchor Link

local ok, reason = exports.lation_banking:EnsureSocietyAccounts(name)

Does what the bank does on its own start: every job the framework knows gets its society account, and every gang while Config > Accounts > Gang accounts too is on. Safe to call any time; nothing is ever closed, and an account outlives the job it was opened for.

• Without a name it returns true, or false, 'societies_disabled' while Config > Accounts > Society accounts is off, when the bank opens none.
• With a name it says whether that account exists afterwards: true (one opened before society accounts went off still counts), or false and societies_disabled, gangs_disabled (a gang, with gang accounts off) or unknown_group (a name the framework doesn't know).

Call it after adding a job while the server runs. The bank also does this on its own when lation_jobs:jobCreated or lation_jobs:jobDeleted fires, and on QBCore when qb-core's AddJob or AddGang adds one.

local ok, reason = exports.lation_banking:EnsureSocietyAccounts('tequilala')
if not ok then print(('no society account for tequilala: %s'):format(reason)) end

SetPosBusinessCopy Anchor Link

local ok = exports.lation_banking:SetPosBusiness(id, rules)

Lists the society under Config > POS > Businesses, as an admin adding it would, so it gets a register; pass nil instead of rules to take it off. Its menu is kept either way.

It merges: only the fields you pass change, so the tax, tax account and menu setting an admin chose stay when you leave them out, and a resource that lists its businesses on every start never resets them. A new entry starts on the section's tax and account, with the menu open to its bosses. Any other key, such as a label, is ignored.

exports.lation_banking:SetPosBusiness('burgershot', {})  -- give Burger Shot a register
exports.lation_banking:SetPosBusiness('burgershot', nil) -- and take it away

SetPosLocationCopy Anchor Link

local ok = exports.lation_banking:SetPosLocation(id, point)

Places a register point under Config > POS > Registers, replacing the one that id already holds; pass nil instead of point to remove it. The points an admin placed from the panel carry no id and are not yours to change. The 50-point limit counts every point.

exports.lation_banking:SetPosLocation('myjobs:14', { label = 'Counter', business = 'burgershot', coords = { x = -1194.2, y = -893.5, z = 13.9, w = 305.0 } })

PlayersCopy Anchor Link

OpenBankCopy Anchor Link

local sent = exports.lation_banking:OpenBank(source, kind)

The usual checks still apply when it opens, such as Hooks.canOpen, the PIN at an ATM, and having a register for pos.

exports.lation_banking:OpenBank(source, 'atm')

RequestPinCopy Anchor Link

local passed = exports.lation_banking:RequestPin(source, accountId)

Puts something of your own behind the bank's PIN. The player sees the PIN pad and the call waits for the answer, which is decided on the server.

• Returns true straight away when Config > ATMs > Ask for a PIN is off or the account has no PIN, so you can always call it and let the server's setting decide.
• Returns false when the player cancels, runs out of tries, already has the bank open, or leaves, and for an unknown accountId.
• Three misses lock the account out for 15 minutes, as at an ATM.

if exports.lation_banking:RequestPin(source) then
    OpenTheSafe(source)
end

SettingsCopy Anchor Link

GetConfigCopy Anchor Link

local section = exports.lation_banking:GetConfig(name)

Coordinates come back as { x, y, z, w } tables. Logging is never returned, so the webhook stays on the server.

local atm = exports.lation_banking:GetConfig('atm')
print(atm.pin) -- false

Business accountsCopy Anchor Link

A business account holds money for your resource: a player-owned shop, a garage, anything with a till that is not a job. Your resource opens it, names its owner and staff, and moves its money; the bank keeps the balance, the number, the PIN and the history, and players see it under Business accounts.

local id = ('myshop:%s'):format(shopId)

exports.lation_banking:CreateAccount({ id = id, type = 'business', name = 'Bean Machine', owner = ownerIdentifier })
exports.lation_banking:AddAccountMember(id, employeeIdentifier, { deposit = true, withdraw = false, transfer = false })

-- a sale at your till
exports.lation_banking:AddAccountMoney(id, 250, 'Order #1042')

-- the shop changes hands, or nobody owns it for now
exports.lation_banking:SetAccountOwner(id, newOwnerIdentifier)
exports.lation_banking:SetAccountOwner(id, nil)

The owner can deposit, withdraw and transfer; members can do what you allowed. Nothing about the account is managed from the bank: players can't rename it, change its members or close it. Business accounts don't count against the shared account limit.

To keep your own copy of the balance in step, listen for lation_banking:transaction and skip the moves your resource made itself.

Client exportsCopy Anchor Link

openBank, openATM, openPos and closeBankCopy Anchor Link

exports.lation_banking:openBank(account) -- the full bank, on that account
exports.lation_banking:openATM()   -- the ATM view
exports.lation_banking:openPos()   -- the register
exports.lation_banking:closeBank() -- closes whichever is open

They go through the server's checks, as a branch or an ATM does. openBank takes an optional account id: the bank opens on that account when the player can use it, and on their own otherwise; lation jobs' Open in bank uses it. openPos is what the ox_inventory item's client.export calls.

isOpenCopy Anchor Link

local open = exports.lation_banking:isOpen()

requestPin (client)Copy Anchor Link

local passed = exports.lation_banking:requestPin(accountId)

if exports.lation_banking:requestPin() then
    OpenLocker()
end

EventsCopy Anchor Link

lation_banking:transactionCopy Anchor Link

AddEventHandler('lation_banking:transaction', function(tx) end)

A local server event fired for every line the bank writes: player actions, exports, the compatibility exports, other scripts' tracked moves, interest, imports and admin adjustments. A report that fills in a line framework tracking already wrote does not fire it again.

AddEventHandler('lation_banking:transaction', function(tx)
    if tx.accountId ~= myAccountId then return end
    if tx.actorName == GetCurrentResourceName() then return end -- our own move
    print(('%s %d, balance now %s'):format(tx.type, tx.amount, tx.balanceAfter))
end)

lation_banking:configUpdatedCopy Anchor Link

AddEventHandler('lation_banking:configUpdated', function(section) end)

A local server event fired after a section is saved and applied. Read the new values with GetConfig.

AddEventHandler('lation_banking:configUpdated', function(section)
    if section == 'currency' then
        local currency = exports.lation_banking:GetConfig('currency')
        print(('the bank now writes money with %s'):format(currency.symbol))
    end
end)

On the client, lation_banking:configUpdated fires with no arguments when a section the client holds (General, Currency, Quick amounts, Branches, Map blip, ATMs or POS) changed.

Compatibility eventsCopy Anchor Link

The events the old banks used still work; see Migrating.

HooksCopy Anchor Link

server/utils/hooks.lua ships open. Edit the functions in place.

canOpenCopy Anchor Link

function Hooks.canOpen(source, kind)

Called before the bank opens. The admin panel does not pass through it.

-- ATMs only for players with a bank card (ox_inventory)
function Hooks.canOpen(source, kind)
    if kind == 'atm' and exports.ox_inventory:Search(source, 'count', 'bank_card') < 1 then
        return false, 'You need your bank card'
    end
    return true
end

canTransactCopy Anchor Link

function Hooks.canTransact(data)

Called before a player's deposit, withdrawal, transfer, bill payment or sale, while nothing has moved yet. For a sale the bill does not exist yet, which makes this the place to refuse one whose goods the customer could not carry. Exports, the compatibility exports, loans and ongoing payments do not call it.

function Hooks.canTransact(data)
    if data.action == 'withdraw' and data.amount > 50000 then
        return false, 'Withdrawals over $50,000 need a manager'
    end
    return true
end

onTransactionCopy Anchor Link

function Hooks.onTransaction(transaction)

Called after every line is written, just before the event fires.

onAccountChangeCopy Anchor Link

function Hooks.onAccountChange(data)

Called when a player opens or closes a shared or savings account, or adds, changes or removes a member, including leaving on their own. Changes made through exports do not call it.

function Hooks.onAccountChange(data)
    if data.action == 'memberAdded' then
        print(('%s was given access to %s'):format(data.identifier, data.accountId))
    end
end

ongoingPaymentsCopy Anchor Link

function Hooks.ongoingPayments(source, identifier)

What the player owes other resources, listed under their bills. Called when the Bills page opens, while bills are on, and cached for 30 seconds, so keep it quick. Up to 20 rows are shown, and an error in it is printed to the console instead of breaking the page.

pay runs under the player's lock, like every money action, and not at an ATM. Its money leaves through the framework, so with tracking on the line it writes is renamed to reason.

function Hooks.ongoingPayments(source, identifier)
    local list = {}

    -- ...keep the jg-dealerships block that ships here...

    list[#list + 1] = {
        id = 'rent:' .. identifier,
        label = 'Apartment rent',
        note = 'Alta Street 12',
        amount = 400,
        dueAt = os.time() + 3 * 86400,
        icon = 'receipt',
        payable = true,
        pay = function(src) return PayRent(src) end
    }
    return list
end

Open codeCopy Anchor Link

These files ship unescrowed, for you to edit: