Bills & requests

Awoken Banking gives every player a single money you owe inbox, shown in the Bills tab of the app (and on the phone). It holds two kinds of entry, and the difference is who’s in control of paying. Everything here is in config/bills.lua.

Request

A one-off invoice a player or script raises against someone - a shop billing a repair, a landlord billing rent, a player splitting a cost. The payer can pay or decline.

Bill

A recurring or official obligation a script pushes in - utilities, subscriptions, fines. Not declinable, can carry a due date, go overdue, and recur. Always fee-free.

Both are paid from the payer’s selected account into the issuer’s account (or a sink if none was named). Turn the whole system off with Config.Bills.enabled = false.

Requests

Requests are the peer / shop billing side. Config.Bills.requests controls what players may do from the UI and the caps on it.

config/bills.lua

requests = {
    allowPlayerBilling = true,
    maxAmount          = 1000000,
    expiryHours        = 48,
    nearbyDistance     = 8.0,
    chargeFee          = true,
},

Setting	What it does	Default
`allowPlayerBilling`	Let players raise requests from the app. `false` = export-only (scripts still bill).	`true`
`maxAmount`	Largest single request (`0` = no cap).	`1000000`
`expiryHours`	Auto-expire an unpaid request after N hours (`0` = never).	`48`
`nearbyDistance`	Range, in metres, for the “bill a nearby player” picker.	`8.0`
`chargeFee`	Apply the transfer fee when a request is paid (`false` = fee-free).	`true`

Bills and overdue

Bills come in through scripts (rent, utilities, fines) and can carry a due date. When that date passes the bill is marked overdue; you can optionally add a one-time late fee and dock the player’s credit score.

config/bills.lua

overdue = {
    lateFeePct         = 0.0,
    creditScorePenalty = 0,
},

Setting	What it does	Default
`lateFeePct`	Fraction of the bill added once when it turns overdue (`0` = none).	`0.0`
`creditScorePenalty`	Credit points lost once when it turns overdue (`0` = none). Needs the loans / credit module.	`0`

creditScorePenalty only does anything when Loans & credit is enabled - that’s where the score lives.

Raising bills from your scripts

Shops, landlords, and utility scripts bill players through the bills exports. A request is declinable; a bill is not.

server-side only

-- A mechanic shop bills a customer for a repair (they can pay or decline)
exports.awoken_banking:createInvoice({
    to     = repairCustomerSrc,     -- server id or citizenid
    from   = 'job:mechanic',        -- where the payment lands
    amount = 2500,
    reason = 'Engine repair',
})

-- A utilities script pushes a recurring power bill, due in 3 days
exports.awoken_banking:createBill({
    owner     = citizenid,
    name      = 'Power & Water',
    amount    = 800,
    category  = 'utility',
    to        = 'job:government',
    dueIn     = 3 * 86400,
    recurring = true,
    everyDays = 7,
})

React to what players do with them through the bills events - onInvoicePaid, onInvoiceDeclined, onBillPaid, onBillOverdue, and more.

Get Started

Awoken Scripts

Request

Bill

Requests

Bills and overdue

Categories

Raising bills from your scripts

Request

Bill

​Requests

​Bills and overdue

​Categories

​Raising bills from your scripts

Requests

Bills and overdue

Categories

Raising bills from your scripts