Server side

🎯 Types

IAccount

lua
---@class IAccount
---@field id string
---@field balance number
---@field createdAt number
---@field iban number
---@field name string
---@field ownerId string
---@field type string
---@field color string
---@field ownedAccount boolean
---@field frozen boolean
---@field closed boolean
---@field settings IAccountSettings
---@field permissions IAccountMemberPermissions

🆔 Accounts

GetSocietyAccount

lua
---@param society string - Society id(police, mechanic...)
---@return IAccount | nil
exports['tgg-banking']:GetSocietyAccount(society)

GetAccountByIban

lua
---@param iban number - The IBAN of the account
---@return IAccount | nil
exports['tgg-banking']:GetAccountByIban(iban)

GetPersonalAccountByPlayerId

lua
---@param playerId number - The session id(source) of the player(0, 25, 150...)
---@return IAccount | nil
exports['tgg-banking']:GetPersonalAccountByPlayerId(playerId)

GetPersonalAccountByPlayerIdentifier

lua
---@param identifier string - The identifier of the player(citizenid, identifier)
---@return IAccount | nil
exports['tgg-banking']:GetPersonalAccountByPlayerIdentifier(identifier)

CreateBusinessAccount

lua
--- Creates a new society account. If the account already exists, it will be returned.
---@param society string
---@param startBalance number?
---@param displayName string?
---@param color string?
---@return { success: boolean, message?: string, error?: string, account?: IAccountView }
exports['tgg-banking']:CreateBusinessAccount(society, startBalance, displayName, color)

💵 Money

GetAccountMoneyByIban

lua
---@param iban number - The IBAN of the account
---@returns number | nil - Account money or nil if the account is not found.
exports['tgg-banking']:GetAccountMoneyByIban(iban)

GetSocietyAccountMoney

lua
---@param society string - Society id(police, mechanic...)
---@returns number | nil - Account money or nil if the account is not found.
exports['tgg-banking']:GetSocietyAccountMoney(society)

AddSocietyMoney

lua
---@param society string - Society id(police, mechanic...)
---@param amount number - The amount you want to add to the account
---@return boolean - Whether the money was added successfully
exports['tgg-banking']:AddSocietyMoney(society, amount)

RemoveSocietyMoney

lua
---@param society string - Society id(police, mechanic...)
---@param amount number - The amount you want to remove from the account
---@return boolean - Whether the money was removed successfully
exports['tgg-banking']:RemoveSocietyMoney(society, amount)

Feel free to request an export to suit your needs.

🪵 Misc

AddTransaction

lua
---@param toIban number | nil - The iban of the account or society name
---@param fromIban number | nil - The iban of the account or society name
---@param transactionType string(deposit, withdraw, transfer, custom) - The type of the transaction
---@param amount number - The amount of the transaction
---@param description string | nil - The description of the transaction
---@param playerId string | nil - The id of the player if the transaction is from a player
---@param cardId number | nil - The id of the card if the transaction is from a card, nil otherwise
---@param customTitle string | nil - Custom title for the transaction (for custom types only)
---@return string | nil - The id of the transaction if successful, nil otherwise
exports['tgg-banking']:AddTransaction(toIban, fromIban, transactionType, amount, description?, playerId?, cardId?)

When adding a withdrawal transaction, the first parameter(toIban) is not required and must be skipped.

lua
exports['tgg-banking']:AddTransaction(nil, 221043, 'withdraw', 2024, 'Your Reason Here')

When adding a deposit transaction, the second parameter(fromIban) is unnecessary and must be skipped.

lua
exports['tgg-banking']:AddTransaction(221043, nil, 'deposit', 2024, 'Your Reason Here')

You can register a custom transaction to match your needs.

lua
exports['tgg-banking']:AddTransaction(nil, 763218, 'vehicle_purchase', 2024, 'Bought Vehicle - Tesla Model S', nil, nil, 'Vehicle Purchase')

IsAccountFrozen

lua
---@param iban number
---@return boolean
exports['tgg-banking']:IsAccountFrozen(iban)

IsAccountTerminated

lua
---@param iban number
---@return boolean
exports['tgg-banking']:IsAccountTerminated(iban)

FreezeAccount

lua
---@param iban number
---@return boolean - Whether the account was frozen successfully
exports['tgg-banking']:FreezeAccount(iban)

UnfreezeAccount

lua
---@param iban number
---@return boolean - Whether the account was unfrozensuccessfully
exports['tgg-banking']:UnfreezeAccount(iban)

TerminateAccount

lua
---@param iban number
---@return boolean - Whether the account was terminated successfully
exports['tgg-banking']:TerminateAccount(iban)

IsCardFrozen

lua
---@param cardId number
---@return boolean
exports['tgg-banking']:IsCardFrozen(cardId)

IsCardTerminated

lua
---@param cardId number
---@return boolean
exports['tgg-banking']:IsCardTerminated(cardId)

FreezeCard

lua
---@param cardId number
---@return boolean - Whether the card was frozen successfully
exports['tgg-banking']:FreezeCard(cardId)

UnfreezeCard

lua
---@param cardId number
---@return boolean - Whether the card was unfrozen successfully
exports['tgg-banking']:UnfreezeCard(cardId)

💳 Loans

GetCreditScore

Get the credit score for a player by their identifier.

lua
---@param playerIdentifier string - The player's identifier (citizenid, identifier)
---@return number | nil - The credit score (300-850) or nil if not found
exports['tgg-banking']:GetCreditScore(playerIdentifier)

GetCreditProfile

Get detailed credit profile for a player including score factors and loan eligibility.

lua
---@param playerIdentifier string - The player's identifier (citizenid, identifier)
---@return table | nil - Credit profile with score, factors, and loan eligibility info
exports['tgg-banking']:GetCreditProfile(playerIdentifier)

Returns:

lua
{
    score = 650,                    -- Credit score (300-850)
    tier = "Fair",                  -- Credit tier (Excellent, Good, Fair, Poor, Bad)
    minScore = 300,
    maxScore = 850,
    factors = {                     -- Score factor breakdown (0-100 each)
        accountAge = 45,
        transactionHistory = 60,
        paymentHistory = 70,
        accountBalance = 30,
        debtToIncomeRatio = 80
    },
    eligibility = {
        canApplyForLoan = true,
        maxLoanAmount = 50000,
        interestRate = 0.24,        -- 24%
        activeLoansCount = 1,
        maxActiveLoans = 3,
        minScoreRequired = 450
    }
}

CanPlayerFinance

Check if a player can finance (take a loan) for a specific amount.

lua
---@param playerIdentifier string - The player's identifier (citizenid, identifier)
---@param amount number - The loan amount to check
---@return boolean - Whether the player can finance this amount
---@return string | nil - Reason if they cannot finance
exports['tgg-banking']:CanPlayerFinance(playerIdentifier, amount)

lua
local canFinance, reason = exports['tgg-banking']:CanPlayerFinance('char1:abc123', 25000)
if canFinance then
    print('Player can finance $25,000')
else
    print('Cannot finance:', reason)
end

CreateLoan

Create a loan application with pending status (for manual approval workflows). Use ApproveLoan or RejectLoan to process the application.

lua
---@param playerIdentifier string - The player's identifier
---@param loanData table - { amount: number, duration: number, paymentFrequency?: string, autoPayment?: boolean }
---@return table - { success: boolean, message?: string, loanId?: number }
exports['tgg-banking']:CreateLoan(playerIdentifier, loanData)

lua
local result = exports['tgg-banking']:CreateLoan('char1:abc123', {
    amount = 10000,
    duration = 30,  -- 30 days
    paymentFrequency = 'weekly',
    autoPayment = true
})

if result.success then
    print('Loan application created:', result.loanId)
    -- Later, approve or reject the loan
    -- exports['tgg-banking']:ApproveLoan(result.loanId)
    -- exports['tgg-banking']:RejectLoan(result.loanId, 'Reason')
end

ApproveLoan

Approve a pending loan application and disburse funds to the player. Player must be online.

lua
---@param loanId number - The loan ID to approve
---@return table - { success: boolean, message?: string, loanId?: number, amount?: number }
exports['tgg-banking']:ApproveLoan(loanId)

RejectLoan

Reject a pending loan application.

lua
---@param loanId number - The loan ID to reject
---@param reason string | nil - Optional rejection reason
---@return table - { success: boolean, message?: string }
exports['tgg-banking']:RejectLoan(loanId, reason)

CreateAndApproveLoan

Create and immediately approve a loan, disbursing funds to the player. Player must be online.

lua
---@param playerIdentifier string - The player's identifier
---@param loanData table - { amount: number, duration: number, paymentFrequency?: string, autoPayment?: boolean }
---@return table - { success: boolean, message?: string, loanId?: number }
exports['tgg-banking']:CreateAndApproveLoan(playerIdentifier, loanData)

Returns on success:

lua
{
    success = true,
    message = "Loan approved and funds disbursed",
    loanId = 123,
    amount = 10000,
    interestRate = 0.24,
    paymentAmount = 850,
    totalAmount = 10600,
    nextPaymentDate = "2024-01-15 12:00:00",
    duration = 30,
    status = "active"
}

GetLoan

Get a specific loan by ID.

lua
---@param loanId number - The loan ID
---@return table | nil - The loan data or nil if not found
exports['tgg-banking']:GetLoan(loanId)

GetPlayerLoans

Get all loans for a player (including paid, defaulted, etc.).

lua
---@param playerIdentifier string - The player's identifier
---@return table[] | nil - Array of loans or nil if error
exports['tgg-banking']:GetPlayerLoans(playerIdentifier)

GetActiveLoans

Get only active loans for a player (status: active or overdue).

lua
---@param playerIdentifier string - The player's identifier
---@return table[] - Array of active loans
exports['tgg-banking']:GetActiveLoans(playerIdentifier)

GetLoanBalance

Get the remaining balance on a loan.

lua
---@param loanId number - The loan ID
---@return number | nil - The remaining balance or nil if loan not found
exports['tgg-banking']:GetLoanBalance(loanId)

GetLoanPaymentDue

Get the next payment due information for a loan.

lua
---@param loanId number - The loan ID
---@return table | nil - Payment due info or nil if loan not found
exports['tgg-banking']:GetLoanPaymentDue(loanId)

Returns:

lua
{
    amount = 850,                       -- Next payment amount
    dueDate = "2024-01-15 12:00:00",   -- Due date
    isOverdue = false,                  -- Whether payment is overdue
    status = "active",                  -- Loan status
    missedPayments = 0                  -- Number of missed payments
}

IsLoanDelinquent

Check if a loan is delinquent (overdue or defaulted).

lua
---@param loanId number - The loan ID
---@return boolean - Whether the loan is delinquent
---@return string | nil - The delinquency status ('overdue', 'defaulted') or nil
exports['tgg-banking']:IsLoanDelinquent(loanId)

ApplyLoanPayment

Apply a payment to a loan. Player must own the loan.

lua
---@param playerIdentifier string - The player's identifier (must own the loan)
---@param loanId number - The loan ID
---@param amount number | nil - Payment amount (nil = regular payment amount)
---@return table - { success: boolean, message?: string, remainingBalance?: number }
exports['tgg-banking']:ApplyLoanPayment(playerIdentifier, loanId, amount)

lua
-- Pass nil as amount to pay the regular installment
local result = exports['tgg-banking']:ApplyLoanPayment('char1:abc123', 123, nil)
if result.success then
    print('Payment applied. Remaining:', result.remainingBalance)
end

PayLoanDue

Pay the current due amount on a loan (convenience wrapper for ApplyLoanPayment).

lua
---@param playerIdentifier string - The player's identifier
---@param loanId number - The loan ID
---@return table - { success: boolean, message?: string, remainingBalance?: number }
exports['tgg-banking']:PayLoanDue(playerIdentifier, loanId)

GetPlayerDebtSummary

Get a comprehensive summary of all player debt.

lua
---@param playerIdentifier string - The player's identifier
---@return table - Debt summary with total debt, active loans, and payment info
exports['tgg-banking']:GetPlayerDebtSummary(playerIdentifier)

Returns:

lua
{
    totalDebt = 25000,              -- Total remaining debt
    activeLoansCount = 2,           -- Number of active loans
    overdueLoansCount = 0,          -- Number of overdue loans
    defaultedLoansCount = 0,        -- Number of defaulted loans
    totalMonthlyPayment = 2500,     -- Estimated total monthly payment
    maxActiveLoans = 3,             -- Maximum allowed active loans
    canTakeMoreLoans = true,        -- Whether player can take more loans
    loans = {                       -- Active loan details
        {
            loanId = 123,
            remainingAmount = 15000,
            paymentAmount = 1500,
            nextPaymentDate = "2024-01-15 12:00:00",
            status = "active",
            missedPayments = 0
        },
        -- ...
    }
}

GetLoanHistory

Get payment history for a specific loan.

lua
---@param loanId number - The loan ID
---@return table[] - Array of payment history records
exports['tgg-banking']:GetLoanHistory(loanId)

Returns array of:

lua
{
    paymentId = 1,
    loanId = 123,
    playerId = "char1:abc123",
    amount = 850,
    paymentType = "manual",     -- 'manual', 'auto', 'early', 'export'
    status = "success",         -- 'success' or 'failed'
    createdAt = "2024-01-08 12:00:00"
}