Vehicle Financing Integration

Guide for exposing externally managed vehicle finance records inside oxide-banking.

This resource does not require a specific vehicle shop framework. The supported integration path is the exported vehicle-loan API in oxide-banking.

Relevant Exports

Use these server exports from your vehicle financing resource (full signatures in Exports & Integration):

RegisterVehicleLoan(data)
RecordVehicleLoanPayment(plate, amount)
CloseVehicleLoan(plate, reason)
GetVehicleLoan(plate)

Intended Flow

Create the financing record

When a financed vehicle sale is created, register the loan with oxide-banking:

local ok, loanIdOrError = exports['oxide-banking']:RegisterVehicleLoan({
    citizenid = citizenid,          -- required: the buyer's character ID
    plate = plate,                  -- required: stored in upper case
    principal = 40000,              -- required: amount financed
    totalAmount = 44000,            -- required: principal plus interest
    paymentAmount = 4400,           -- required: one instalment
    paymentsTotal = 10,             -- required: number of instalments
    paymentsRemaining = 10,         -- optional: defaults to paymentsTotal
    interestRate = 0.06,            -- optional: defaults to 0.06, shown in the bank
    vehicleModel = 'sultan',        -- optional: defaults to 'Unknown'
})

The remaining balance is set to paymentAmount x paymentsRemaining. Only one open loan can exist per plate. Registering a loan records a loan_opened credit event for the buyer, and the loan counts toward their total borrowing limit (Config.Loans.exposure).

Record installment payments

Whenever your shop resource collects a vehicle finance payment, also record that payment in oxide-banking with RecordVehicleLoanPayment(plate, amount). Each call counts as one instalment and one on-time payment for the player's credit score. When the balance reaches zero the loan is marked paid.

Close the vehicle loan

When the financing is fully repaid, repossessed, or otherwise closed, call CloseVehicleLoan(plate, reason) so it disappears from active loan views. reason = 'repossessed' marks the loan defaulted and records a loan_defaulted credit event. Any other reason (default 'paid') marks it paid and records loan_paid_off.

Your resource owns collection

The bank never debits a registered vehicle loan: it is excluded from scheduled loan collection, and the Pay and Pay Off actions are hidden on it in the bank UI. The bank also never marks a vehicle loan as late or sends it to collections.

Config Notes

config/loans.lua includes:

config/loans.lua

Config.Loans.externalTypes = {
    ['vehicle'] = {
        label = 'Vehicle Financing',
        description = 'Managed by dealership',
        icon = 'fa-car',
    },
}

That external type is what gives vehicle finance records their name and icon in the banking UI.

Collateral Seizure

config/loans.lua has a Config.Loans.collections.collateralHandlerResource setting, meant to name a resource that exports SeizeLoanCollateral(citizenid, collateralType, collateralId, loanId).

Not currently used

The current version of the bank never calls SeizeLoanCollateral, so setting collateralHandlerResource has no effect. Handle repossession in your own resource, then call CloseVehicleLoan(plate, 'repossessed').

Verification

Create a financed vehicle purchase in your vehicle system.
Register the loan in oxide-banking.
Open the banking UI and confirm the vehicle loan appears in the loan view.
Record a payment and confirm the outstanding balance updates.
Close the loan and verify it leaves the active-loan view.

Notes

oxide-banking does not depend on any specific vehicle shop resource. Any dealership or financing script can integrate through the exports above, regardless of framework.

On this page