Fleeca Bank — Full Documentation

Overview

Fleeca Bank is a full-featured roleplay banking system composed of two independent products that work together:

Requirements

Web System

FiveM Bridge

Architecture

The following diagram shows how the two systems communicate:

┌─────────────────────────────────────────────────────────┐
│                     BROWSER (Player)                    │
│  ┌─────────────────────────────────────────────────┐   │
│  │            Fleeca Bank Web Dashboard             │   │
│  │  Login / Accounts / Loans / Savings / Invoices  │   │
│  └──────────────────────┬──────────────────────────┘   │
└─────────────────────────┼───────────────────────────────┘
                          │ HTTPS
┌─────────────────────────▼───────────────────────────────┐
│                   WEB SERVER (cPanel)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │  config.php │  │  api/*.php  │  │  admin/*.php   │  │
│  └─────────────┘  └──────┬──────┘  └────────────────┘  │
│                          │ PDO                           │
│  ┌───────────────────────▼───────────────────────────┐  │
│  │                MySQL Database                     │  │
│  └───────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────┘
                           │ HTTPS + X-Fleeca-Key
┌──────────────────────────▼──────────────────────────────┐
│                  FIVEM SERVER (txAdmin)                 │
│  ┌────────────────────────────────────────────────────┐ │
│  │              fleeca-fivem resource                 │ │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────────────┐  │ │
│  │  │config.lua│  │server/   │  │ client/ + html/  │  │ │
│  │  └──────────┘  │main.lua  │  │ NUI Interface    │  │ │
│  │                └──────────┘  └─────────────────┘  │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

All sensitive operations (token generation, banking actions) go through the server-side Lua scripts, which call the web API using PerformHttpRequest. The NUI (client-side) never talks to the web server directly.

Web System — Installation

Web System — Configuration

All configuration lives in config.php at the root of the installation.

Database

// config.php
define('DB_HOST', 'localhost');
define('DB_NAME', 'fleeca_bank');    // Your MySQL database name
define('DB_USER', 'fleeca_user');    // Your MySQL username
define('DB_PASS', 'YOUR_PASSWORD');  // ← Change this

Security

define('JWT_SECRET', '64_random_characters_minimum'); // ← Change this
define('JWT_EXPIRY', 3600 * 8);  // Session duration: 8 hours
define('APP_URL',    'https://your-site.com/fleeca-bank'); // ← Change this

Banking limits

define('PERSONAL_WEEKLY_LIMIT',     10000.00);  // Personal accounts: $10k/week
define('PROFESSIONAL_WEEKLY_LIMIT', 500000.00); // Professional: $500k/week
define('PROFESSIONAL_TAX_PERCENT',      5.15); // % fee on pro transactions
define('MAX_LOAN_AMOUNT',           500000);    // Global max loan
define('MIN_LOAN_AMOUNT',             1000);    // Global min loan
define('MAX_LOAN_WEEKS',               52);    // Max repayment duration
define('INTEREST_RATE_DEFAULT',         1.5);    // % weekly loan interest

Language

define('LANG', 'en'); // 'en' | 'fr' | 'de' | 'es'

FiveM integration

define('FIVEM_SECRET',       'your_shared_secret'); // Must match Config.SecretKey in config.lua
define('FIVEM_TOKEN_EXPIRY', 30);     // One-time token validity (seconds)
define('FIVEM_MAX_DEPOSIT',  500000); // Max deposit per transaction
define('FIVEM_MAX_WITHDRAW', 50000);  // Max withdrawal per transaction
define('FIVEM_MAX_TRANSFER', 100000); // Max transfer per transaction

Discord webhooks

define('DISCORD_WEBHOOK_ENABLED',  true);
define('DISCORD_WEBHOOK_MAIN',     'https://discord.com/api/webhooks/...'); // General events
define('DISCORD_WEBHOOK_TRANSFERS','https://discord.com/api/webhooks/...'); // Transfers only
define('DISCORD_WEBHOOK_SECURITY', 'https://discord.com/api/webhooks/...'); // Login / security
define('DISCORD_WEBHOOK_CRON',     'https://discord.com/api/webhooks/...'); // Cron reports

Web System — File Structure

Web System — Roles & Permissions

Web System — Features

Accounts

Each client has one bank account with a unique IBAN (format: FLEECA-XXXXXX). Accounts can be typed as personal or professional, each with different transfer limits and fee rules. Admins can freeze or unfreeze any account.

Loans

Clients submit loan requests specifying amount and duration (in weeks). Bankers approve or deny. Once approved, the amount is credited to the account and weekly repayments are processed automatically by the cron job. Interest rate defaults to INTEREST_RATE_DEFAULT (configurable per loan by bankers). Overdue loans incur an additional LATE_PENALTY_RATE per week.

Savings Accounts

Clients can open savings sub-accounts with a configurable interest rate and lock period. The cron job applies interest weekly. Savings balances are separate from the main account and cannot be used for transfers until the lock expires.

Invoices

Clients and bankers can create invoices sent to other accounts by IBAN. The recipient receives a notification and can pay directly from their dashboard. Invoices support custom line items, due dates, and PDF export.

Employee Salaries

Admins can register employees and configure their weekly salary. The cron job automatically credits salaries every week on the configured SALARY_DAY.

Translations (i18n)

The system supports English, French, German, and Spanish. The active language is set in config.php:

define('LANG', 'en'); // 'en' | 'fr' | 'de' | 'es'

Translation strings live in langs/en.php, langs/fr.php, etc. To add or modify strings, edit the corresponding file. Use __t('key') in templates for escaped output and __tr('key') for raw HTML.

Web System — Cron Jobs

Add the following job in cPanel → Cron Jobs. Set it to run once per week (e.g. every Sunday at midnight):

0 0 * * 0  php /home/YOUR_CPANEL_USER/public_html/fleeca-bank/cron/process.php

The cron script handles:

Web System — Discord Webhooks

Set DISCORD_WEBHOOK_ENABLED to true and fill in the webhook URLs. Each channel is independent — you can use the same webhook for all or separate channels per event type.

FiveM Bridge — Installation

FiveM Bridge — Configuration

All bridge configuration is in config.lua at the root of the resource.

Config.Framework = 'ESX'         -- 'ESX' | 'QBCore' | 'Standalone'
Config.WebURL    = 'https://your-site.com'  -- No trailing slash
Config.SecretKey = 'your_shared_secret'     -- Must match FIVEM_SECRET in config.php

Config.MaxDeposit  = 500000   -- Server-side cap per deposit
Config.MaxWithdraw = 50000    -- Server-side cap per withdrawal
Config.MaxTransfer = 100000   -- Server-side cap per transfer

Config.NotifyStyle         = 'esx'  -- 'esx' | 'qbcore' | 'ox' | 'standalone'
Config.InteractionDistance = 2.0   -- Meters to trigger ATM interaction
Config.TokenExpiry         = 30    -- One-time auth token validity (seconds)

FiveM Bridge — File Structure

FiveM Bridge — Frameworks

The bridge uses a Bridge object pattern. The active framework file populates it before main.lua runs. You only need to set Config.Framework — no other changes required.

FiveM Bridge — ATM & Access Points

Access points are defined in Config.AccessPoints. Three types are supported:

type = 'atm' — Spawn a new ATM prop

{
    type   = 'atm',
    coords = vector4(149.5, -1042.7, 29.4, 340.0),
    label  = '🏧 Fleeca ATM',
    model  = 'prop_fleeca_atm',  -- optional, overrides Config.ATMModel
},

type = 'ped' — Spawn a banker NPC

{
    type     = 'ped',
    coords   = vector4(151.2, -1041.5, 29.4, 160.0),
    label    = '🏦 Fleeca Banker',
    model    = 'mp_m_freemode_01',
    animDict = 'WORLD_HUMAN_STAND_IMPATIENT',
    animName = 'BASE',
},

type = 'existing' — Auto-detect map ATMs

{
    type  = 'existing',
    label = '🏧 Fleeca ATM',
},

Scans all objects loaded by GTA every second using GetGamePool("CObject") and matches them against Config.ATMModels. Detected ATMs are registered as interactive automatically — no coordinates needed. Works with MLOs and any prop placed by other scripts.

ATM Models

Interaction

If ox_target is present, interactions are registered via exports.ox_target:addLocalEntity. Otherwise, the bridge falls back to a proximity loop that shows a "Press E" hint and listens for key input.

FiveM Bridge — Account Linking

Before a player can use ATMs, their FiveM Steam license must be linked to their Fleeca Bank web account.

Linking flow

To unlink, the player can return to link-fivem.php and click Unlink, or an admin can clear the license from the web admin panel.

FiveM Bridge — NUI Interface

The NUI is a dark-themed single-page interface that opens when a player interacts with an ATM or banker NPC. It displays:

The NUI closes with the ✕ button, the Escape key, or automatically after a successful transaction (1.8s delay). Mouse focus is fully released on close.

FiveM Bridge — Events Reference

Client → Server

Server → Client

NUI Callbacks (JS → Lua)

API — fivem_auth.php

Called by the FiveM server scripts via PerformHttpRequest. All requests must include the header X-Fleeca-Key: {FIVEM_SECRET}.

POST — request_token POST

Generates a one-time auth token for a player. Returns account data.

// Request
{
  "action":  "request_token",
  "license": "license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "secret":  "your_shared_secret"
}

// Response 200
{
  "token":        "abc123...",
  "balance":      15420.50,
  "iban":         "FLEECA-000042",
  "transactions": [ ... ]
}

// Response 401 — bad secret
{ "error": "Unauthorized." }

// Response 404 — license not linked
{ "error": "No account found for this license." }

POST — bank_action POST

Executes a banking transaction.

// Request
{
  "action":      "bank_action",
  "bank_action": "deposit",   // "deposit" | "withdraw" | "transfer"
  "license":     "license:xxx",
  "amount":      5000,
  "to_iban":     "FLEECA-000007",  // required for transfer only
  "description": "Rent payment",   // optional
  "secret":      "your_shared_secret"
}

// Response 200
{
  "success":      true,
  "message":      "Deposit successful.",
  "balance":      20420.50,
  "transactions": [ ... ]
}

GET — get_data GET

Returns current balance and recent transactions for background refresh.

GET /api/fivem_auth.php?action=get_data&license=license:xxx&secret=your_secret

// Response 200
{
  "balance":      20420.50,
  "iban":         "FLEECA-000042",
  "transactions": [ ... ]
}

API — fivem_link.php

POST — generate POST

Called by the FiveM server when a player types /linkbank. Generates a 6-digit code.

{
  "action":  "generate",
  "license": "license:xxx",
  "secret":  "your_shared_secret"
}

// Response 200
{ "code": "483921", "expires_in": 600 }

POST — verify POST

Called by link-fivem.php when the player submits their code in the browser. Requires the player to be logged in (session).

{
  "action":     "verify",
  "code":       "483921",
  "csrf_token": "..."
}

// Response 200
{ "success": true }

// Response 422 — invalid or expired code
{ "error": "Invalid or expired code." }

Database — Key Tables

Database — Migrations

If you already have the web system installed and are adding FiveM support, import only the FiveM migrations — do not re-run fleeca_bank_install.sql.

Escrow / CFX

The FiveM bridge is designed for distribution via the CFX Asset Store or Tebex with optional escrow. The following files must remain unescrowd so buyers can configure the resource:

Add to fxmanifest.lua:

escrow_ignore {
    'config.lua',
    'fxmanifest.lua',
    'html/index.html',
    'html/style.css',
}

Security Notes

Secret key

The FIVEM_SECRET / Config.SecretKey is the shared key between your web server and FiveM server. It is sent as the X-Fleeca-Key HTTP header on every API call. Use a long random string (32+ characters). Never commit it to a public repository.

Server-side validation

All amount and action validation happens server-side in Lua (server/main.lua) before calling the web API. The NUI never communicates with the web API directly — all NUI fetch calls go to the Lua callback system via https://{resource_name}/{callback}.

One-time tokens

Each time a player opens an ATM, the server generates a short-lived token (default 30 seconds). This token is used to authenticate the session. It cannot be reused and expires automatically.

Troubleshooting