Installation

danger

The resource folder must be named wasabi_billing.

Before installing

1. Install the required dependencies.
2. Back up the database and existing billing resource/configuration if replacing an installation. Read Migration before the first start.
3. Stop and remove the replaced billing resource from the startup list. Do not run two invoice systems against the same billing events or tables.
4. Keep your banking resource: billing replaces invoicing, not banking.

The manifest provides okokBilling, esx_billing, and codem-billing. Disabling a compatibility switch does not remove these manifest declarations. Do not run the original resources alongside this replacement.

Resource and startup order

Extract the package into your resources directory as wasabi_billing. Start the framework and chosen providers before billing, following those providers' own dependency order.

Example for QBCore with Wasabi Banking and ox_inventory:

ensure ox_lib
ensure oxmysql
ensure qb-core
# Start each optional provider's dependencies before the provider itself.
ensure ox_inventory
ensure wasabi_banking
ensure wasabi_billing

For personal billing without society banking or physical items:

-- config/server/config.lua
Config.BankingIntegration = 'none'

-- config/shared/config.lua
Config.InvoiceItem = false

Database setup

Leave Config.AutomaticAddDatabaseTables = true for initial setup. Billing creates or patches the wasabi_billing table through oxmysql; there is no separate SQL file to import for a standard installation.

The database user needs table creation, alteration, index, and normal read/write permissions while automatic setup is enabled. If you disable automatic setup, provision the complete schema from escrow/billing/server/modules/database.lua yourself first. Disabling setup does not disable SQL use.

Check for [wasabi_billing][db] errors and module initialization failures. A general “Server started” line is not proof that every schema operation succeeded. Existing installations also need the classification and duplicate-reference checks in Migration.

Admin permissions

The default admin ACE is wsbbilling. Grant it to the principal your server actually uses, for example:

# ESX/admin principal example
add_ace group.admin wsbbilling allow

# QBCore god principal example
add_ace qbcore.god wsbbilling allow

You do not need both examples unless both principals are intentionally used. Framework admin checks are also accepted: ESX admin, superadmin, or owner; QBCore/QBOX admin or god through their permission API. On QBOX, the explicit ACE is useful when the framework permission compatibility API is unavailable.

Admin access enables citizen/society inspection and destructive record management. It does not automatically grant a job's send-as-society grade or make the ordinary Society tab show every society.

Invoice item

Skip this section if Config.InvoiceItem = false. The default item name is invoice; examples also ship in _INSTALL_FIRST/README.md.

ox_inventory

Add this entry inside ox_inventory/data/items.lua:

['invoice'] = {
    label = 'Invoice',
    weight = 0,
    stack = false,
    close = true,
    description = 'An unpaid invoice.',
    client = { image = 'invoice.png' },
    server = { export = 'wasabi_billing.invoice' },
    consume = 0,
},

The item export is registered only when ox_inventory is the selected backend and the invoice item is enabled. If you change Config.InvoiceItem to bill, rename the item entry and use server = { export = 'wasabi_billing.bill' }.

qb-inventory / ps-inventory

Add this entry inside qb-core/shared/items.lua:

['invoice'] = {
    name = 'invoice',
    label = 'Invoice',
    weight = 0,
    type = 'item',
    image = 'invoice.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'An unpaid invoice.',
},

Keep unique = true so each copy retains its own invoice metadata, and useable = true so it can open the receipt.

Other included inventory bridges

• codem-inventory: Use the QB-style definition and add it to CodeM's own item list if your version maintains one. The supplied usable-item bridge requires the qb-core export surface.
• tgiann-inventory: Use the QB-style definition with its supported framework setup. The supplied usable-item bridge also requires the qb-core export surface.
• jaksam_inventory: Register the invoice through its item manager with usable-item support enabled. The bridge normalizes metadata from ESX/QB callback shapes.

Copy _INSTALL_FIRST/invoice.png to the inventory's image directory: ox_inventory/web/images/ or the relevant QB-style <inventory>/html/images/ directory.

Metadata includes reference_id, description, sender, reason, amount (the invoice total), and due. A copy is handed to an online personal recipient when an invoice is created. There is no login-time delivery queue, society-item delivery, or automatic item removal after payment. A full inventory can prevent the item from being added without removing the invoice record.

A transferred item opens the referenced invoice, but its receipt Pay button is limited to the billed party. Another player should copy its reference and use /payreference to pay a personal invoice from their own funds.

First-use checklist

• Open /billing or press F7; close the UI and confirm the cursor/focus returns to the game.
• Use two characters within the configured distance to create a small personal invoice. Self-invoicing is rejected.
• Check stored amount, VAT, deadline, reference, received/sent lists, cash payment, and bank payment.
• Verify physical item metadata/use if enabled, and third-party payment through /payreference.
• Test both sending and management grades for your society, including a lower-grade character who must be denied.
• Test society balances, issuer payout, employee commission, and optional VAT routing against your actual banking provider.
• Check staff inspection and logging with an authorized and an unauthorized character.
• Test offline payouts and overdue collection on a staging server before enabling automatic collection in production.

For troubleshooting and debug-command limitations, see Using Billing.