Server side

🎯 Types

IAccount

---@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

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

GetAccountByIban

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

GetPersonalAccountByPlayerId

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

GetPersonalAccountByPlayerIdentifier

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

CreateBusinessAccount

--- 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

---@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

---@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

---@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

---@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 removed successfully
exports['tgg-banking']:RemoveSocietyMoney(society, amount)

Feel free to request an export to suit your needs.

🪵 Misc

AddTransaction

---@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?)

Example: Withdraw transaction

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

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

Example: Deposit transaction

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

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

Example: Custom transaction

• You can register a custom transaction to match your needs.

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

IsAccountFrozen

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

IsAccountTerminated

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

FreezeAccount

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

UnfreezeAccount

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

TerminateAccount

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

IsCardFrozen

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

IsCardTerminated

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

FreezeCard

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

UnfreezeCard

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

💳 Loans

All loan exports require the loan system to be enabled in config.loans.lua. These exports can only be called from the server side.

GetCreditScore

Get the credit score for a player by their identifier.

---@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)

Example

local creditScore = exports['tgg-banking']:GetCreditScore('char1:abc123')
if creditScore then
    print('Player credit score:', creditScore)
end

GetCreditProfile

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

---@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:

{
    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.

---@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)

Example

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.

---@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)

Example

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.

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

Example

local result = exports['tgg-banking']:ApproveLoan(123)
if result.success then
    print('Loan approved! $' .. result.amount .. ' disbursed to player')
end

RejectLoan

Reject a pending loan application.

---@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)

Example

local result = exports['tgg-banking']:RejectLoan(123, 'Insufficient collateral')
if result.success then
    print('Loan application rejected')
end

CreateAndApproveLoan

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

---@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:

{
    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.

---@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.).

---@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).

---@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.

---@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.

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

Returns:

{
    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).

---@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)

Example

local isDelinquent, status = exports['tgg-banking']:IsLoanDelinquent(123)
if isDelinquent then
    print('Loan is delinquent:', status)  -- 'overdue' or 'defaulted'
end

ApplyLoanPayment

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

---@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)

Example: Pay specific amount

local result = exports['tgg-banking']:ApplyLoanPayment('char1:abc123', 123, 5000)
if result.success then
    print('Payment applied. Remaining:', result.remainingBalance)
end

Example: Pay regular installment

-- 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).

---@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.

---@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:

{
    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.

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

Returns array of:

{
    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"
}