Skip to content

Chapter 13 — Accounts Payable

Book 3 · Procurement & Suppliers · Bizwiz Guide Scope: how a received purchase becomes money owed to a supplier, and how that money is eventually paid — the creditor ledger, supplier invoices, bills, credit/debit notes, advance payments, and the payment-voucher → cheque/EFT → settlement machinery, plus the statutory tails (withholding, VAT, PAYE/NHIF/NSSF).

1. Purpose (plain language)

Accounts Payable (AP) is the "what we owe our suppliers, and how we pay it" side of Bizwiz. Book 2 Chapter 9 covered receiving goods (the GRN — Goods Received Note). This chapter picks up the moment those received goods (or services) turn into a bill we owe, and follows the money all the way out the door.

Three everyday questions this module answers:

  1. How much do we owe each supplier right now? — the creditor ledger (wa_supp_trans), one row per invoice / credit note / adjustment, with a running "how much of this is still unpaid" figure.
  2. How does a delivery become a payable? — a receiving clerk matches the supplier's invoice against the GRN, prices are confirmed, and the system posts the invoice to the ledger and to the General Ledger (creditors control account goes up).
  3. How do we actually pay? — a payment voucher is raised for one or more invoices, approved, and then settled by cheque, bank transfer / EFT (bundled into a "bank file" sent to the bank, e.g. Equity host-to-host), or from a safe/cash account. Along the way the system withholds tax where the supplier is subject to it, and can pay statutory bodies (KRA VAT, PAYE, NHIF, NSSF) through the same voucher rails.

Who cares: procurement & stores (they create the invoice from the GRN), finance/AP clerks (raise and allocate vouchers), approvers/financial controllers (approve vouchers, confirm details, send to bank), and auditors (every step is permission-gated and leaves a ledger + GL trail).

The dominant design pattern here — the same one seen across Bizwiz — is approval queues everywhere: an invoice is posted by one person but approved by another; a voucher is prepared, then approved, then confirmed (sometimes two-step), then sent to bank. This is rich territory for the "approvers not curators" AI goal: much of the human effort is re-keying, matching, and eyeballing amounts that the system already has the data to pre-fill or pre-check.

2. Users & roles (permissions & flags)

AP is gated by the standard Bizwiz permission strings (module___action, checked via the can($action, $model) helper and $my_permissions), with role_id == 1 / superadmin bypass. The permission surface for this chapter:

Area Permissions (module___action)
Supplier invoicing suppliers-invoice___view, suppliers-invoice___add, suppliers-invoice___edit, suppliers-invoice___reverse
GRN approval (invoice posting) grn_pending_approval___process (alternative gate on supplier_invoice_process)
Credit / debit notes credit-debit-notes___view, credit-debit-notes___add, credit-debit-notes___edit
Opening balance invoices opening-balance-invoices___view, opening-balance-invoices___add, opening-balance-invoices___edit
Payment vouchers payment-vouchers___view, payment-vouchers___add, payment-vouchers___edit, payment-vouchers___reverse-voucher, payment-vouchers___confirm-details, payment-vouchers___approve-confirmation
Bank files (EFT) bank-files___view, bank-files___add, bank-files___send-to-bank
Voucher cheques payment-voucher-cheques___view, payment-voucher-cheques___add, payment-voucher-cheques___bounce, payment-voucher-cheques___clear
Outgoing cheque verification outgoing-cheque-verification___view, outgoing-cheque-verification___run-verification, outgoing-cheque-verification___verify-bulk-transactions
Withholding tax withholding-tax-payments___view/add/approve, withholding-files___view/add
VAT payments vat-payments___view/add/approve
Statutory payments statutory-payments___view/add
GL payments gl-payments___view/add/approve

Separation-of-duties signals in the code (prime audit/AI targets): - Invoice posting vs approval: supplier_invoice_process accepts either suppliers-invoice___add or the approval-workflow gate grn_pending_approval___process, and routes through TaskCenterService::assertCanAct('supplier_invoice_posting', …) when it's an approval request. - Voucher approve (can('edit', …)) is distinct from confirm (confirm-details) and confirm-approval (approve-confirmation) — a two-step confirmation where the confirmer and the confirmation-approver must be different permission holders. - Reversal is its own permission (reverse-voucher) and is blocked once a voucher is in a bank file.

INFERENCE: which of these gates are actually assigned to distinct people (vs one super-user holding all) is tenant-configuration, not code — a standing "which is live per client" question. CODE-PROVEN: the capability to separate them exists.

3. Processes (end to end)

3.0 The AP big picture

flowchart TD
    GRN[GRN received<br/>Book 2 Ch9] -->|match supplier invoice| INV[Supplier Invoice posted]
    BILL[Supplier Bill<br/>non-PO services] --> LEDGER
    OB[Opening Balance Invoice] --> LEDGER
    INV -->|creates row| LEDGER[(wa_supp_trans<br/>CREDITOR LEDGER)]
    CN[Credit / Debit Note] -->|adjusts| LEDGER
    LEDGER -->|select unpaid| PV[Payment Voucher]
    ADV[Advance Payment] -.allocates.-> LEDGER
    PV -->|approve| PVA[Voucher APPROVED]
    PVA -->|cheque| CHQ[Cheque issued]
    PVA -->|EFT| BF[Bank File → Bank/Equity H2H]
    PVA -->|safe/cash| SAFE[Safe withdrawal]
    CHQ --> SETTLE[Invoice settled]
    BF --> SETTLE
    SAFE --> SETTLE
    PVA --> GL[(wa_gl_trans<br/>DR Creditors / CR Bank)]
    PVA -.WHT.-> WHT[Withholding tax accrued → paid to KRA]

3.1 GRN → Supplier Invoice (the payable is born)

This is the seam back to Book 3 Ch12 (Purchases) and Book 2 Ch9 (GRN). Handled by SupplierController (app/Http/Controllers/Admin/SupplierController.php).

stateDiagram-v2
    [*] --> GRN_Received: goods in (Ch9)
    GRN_Received --> Invoicing: supplier_invoice_order_details()\nmatch supplier invoice #, adjust prices
    Invoicing --> PendingApproval: supplier_invoice_process()\n(approval workflow on)
    Invoicing --> Posted: supplier_invoice_process()\n(no approval workflow)
    PendingApproval --> Posted: approver processes\n(grn_pending_approval___process)
    Posted --> [*]: WaSuppTran created, GL posted,\nwa_grns.invoiced=1

Key method: supplier_invoice_process() (SupplierController.php:2334), all inside a DB transaction (:2451–2721):

  1. Double-post guard (:2457–2463): row-locks wa_grns; if invoiced = 1 already → throws GRN_ALREADY_INVOICED.
  2. Approval-workflow branch (:2466–2478): verifies GRN is invoice_approval_status = 'Pending Approval', calls TaskCenterService::assertCanAct('supplier_invoice_posting', …), else GRN_NOT_PENDING_APPROVAL.
  3. Creates the creditor-ledger row WaSuppTran (:2522–2549): document_no/suppreference = supplier's invoice number; supplier_no; trans_date; due_date from payment terms (:2537); settled = 0; total_amount_inc_vat = line totals + VAT; VAT split; cu_invoice_number; prepared_by.
  4. Marks the GRN invoiced (WaGrn.invoiced = 1, invoice_approval_status = 'Approved' if approval branch) (:2551–2562).
  5. Creates the invoice header WaSupplierInvoice (:2564–2577) linking wa_supp_tran_id, grn_number, supplier_invoice_number, cu_invoice_number; invoice number via getCodeWithNumberSeries("SUPPLIER_INVOICE_NO").
  6. Creates line items WaSupplierInvoiceItem, one per PO line (:2585–2602).
  7. GL posting (:2652–2703) — see §3.6.
  8. Closes the PO (WaPurchaseOrder.invoiced = "Yes") only when all GRNs/invoices sum to the PO total (:2705–2714).
  9. Fires SupplierInvoiceCreated (:2718) — trade-discount listeners post atomically inside the transaction.

Processed-invoice list & lifecycle (ProcessedInvoiceController.php): index() (:39) buckets invoices into pending (no payment_voucher_items, no advance_payment_allocations), paid (voucher PROCESSED or has advance allocation), progress (voucher exists but not yet PROCESSED). update() (:335) keeps wa_supplier_invoices, wa_supp_trans, and wa_gl_trans.transaction_no in sync; reverse() (:397) delegates to the ReverseSupplierInvoice action.

3.2 Supplier Bills (non-PO payables)

supplier_bills is the alternative AP entry for costs not tied to a purchase order (services, utilities, professional fees). Same ledger destination — it participates in payment vouchers via the polymorphic payment_voucher_items.payable_type = 'bill'. Carries its own withholding_amount, allocated_amount, status, and (since 2026 migrations) a VAT breakdown and WHT-processed flag.

3.3 Opening Balance Invoices

opening_balance_invoices (OpeningBalanceInvoiceController) captures prior-period debt when a client goes live — analogous to opening receivables on the debtor side. store() (:145) writes the invoice + a journal entry against the creditors-opening-balance GL account (WaCompanyPreference.creditorOpeningBalanceGlAccount). Status is pending / paid.

3.4 Credit & Debit Notes

FinancialNoteController handles both, distinguished by financial_notes.type = 'CREDIT' or 'DEBIT'.

flowchart LR
    subgraph Create [store :204]
        A[financial_notes row<br/>type CREDIT/DEBIT] --> B[wa_supp_trans row<br/>+ve for DEBIT / -ve for CREDIT]
    end
    B --> C{allocate :708}
    C -->|CREDIT to invoice/bill/fuel| D[link wa_supp_tran_id /<br/>supplier_bill_id / fuel_invoice_id]
    C -->|affects_debtors| E[processDebtorAllocations<br/>wa_debtor_trans -ve +<br/>customer_credits]
    C -.DEBIT cannot allocate to invoices.-> X[blocked :717]
  • Sign rule (:289): a DEBIT note posts total_amount_inc_vat positive (increases what we owe); a CREDIT note posts it negative (reduces it).
  • CREDIT allocation (allocate() :708): can offset supplier invoices, bills, debit notes, or fuel invoices; validates the target isn't already settled (:816) and that there's an allocatable balance (creditNoteAllocatableBalance(), :821).
  • Supplier credit passed to a customer (affects_debtors = true): processDebtorAllocations() (:887–1001) writes a negative wa_debtor_trans (channel 'Supplier Credit Note'), optionally a customer_credits "available" remainder, and a one-sided GL credit to debtors control (the counterpart was posted at the original debtor invoice).

3.5 Payment Vouchers → Cheque / EFT / Cash (paying it out)

The heart of AP settlement. PaymentVoucherController + ProcessVoucher action + BankFilesController + VoucherChequeController.

State machine — payment_vouchers.status (PaymentVoucher.php:21–27): PENDING=0, APPROVED=1, PROCESSED=2, BOUNCED=3.

stateDiagram-v2
    [*] --> PENDING: store() raises voucher\n(allocates to invoices)
    PENDING --> APPROVED: approve() can('edit')\n+document_number, ProcessVoucher
    PENDING --> Deleted: decline() removes voucher
    APPROVED --> Confirmed: confirm()\ntwo-step: confirm-details + approve-confirmation
    APPROVED --> PENDING: reverse() reverse-voucher\n(blocked if in bank file)
    Confirmed --> PROCESSED: BankFile store() / send-to-bank
    APPROVED --> PROCESSED: cheque/cash path
    PROCESSED --> BOUNCED: cheque bounce()

Raising a voucher (store(), :2021–2259): inserts payment_vouchers (supplier, bank account, payment mode, amount = sum of allocations), one payment_voucher_items per payable, and updates each target wa_supp_trans.allocated_amount. The allocation formula (:2603, and storeInvoiceItems :2871+):

allocated_amount := allocated_amount − voucherPaymentsTotal(thisVoucher) + toPay

subtracting any prior payment on this voucher (so edits are idempotent) then adding the new amount. A transaction is stamped settled = true when its outstanding (WaSuppTranOutstandingService::calculate().pending_amount) drops below 1.0 (:2930–2945). Partial payment is gated by the allow-supplier-invoices-partial-payment setting (:554).

Payable variety — one voucher can pay many kinds of things via the polymorphic payable_type: invoice (WaSuppTran), bill (SupplierBill), advance (AdvancePayment), petty_cash_lpo (PettyCashPurchaseOrder), fuel (FuelInvoice), jv (journal voucher), plus consumable_invoice, tyre_invoice, debit_note.

Approval (approve() :4616–4741): sets status = APPROVED, assigns document_number, stamps approved_by/at, creates a safe_withdrawal_request for safe accounts (:4637–4646), and calls ProcessVoucher::process() (:4655).

ProcessVoucher::process() (app/Actions/PaymentVoucher/ProcessVoucher.php:24–222) is where the money actually moves in the ledgers: - wa_supp_trans — payment rows keyed by the voucher number as document_no; one for the bank payment, one for WHT; total_amount_inc_vat negative (reduces the payable). - wa_bank_trans — bank-ledger row (bank_gl_account_code, reference = voucher number, amount). - wa_gl_trans — DR Creditors / CR Bank, plus DR Creditors / CR WHT-liability, via GlTransactionService::post(). - Sets is_processed_withholding_tax = true on the paid WaSuppTran / SupplierBill.

Cheque path (VoucherChequeController, PaymentVoucherCheque.php:21–28): cheque types normal / open (blank, consumed later with a specific amount) / postdated (auto-flagged if dated in the future and the setting is on). Status lifecycle issued → consumed → cleared (ClearPostdatedCheque) → bounced (BounceChequeService). Bouncing sets voucher BOUNCED and records bounce_date/reason + a bounced_cheque_demand_id.

Bank-file / EFT path (BankFilesController.php:127–287): collects APPROVED/PROCESSED vouchers on a single bank account, groups them into wa_bank_files + wa_bank_file_items, runs ProcessVoucher if not already processed, and flips vouchers to PROCESSED. sendToEquityBankH2H() (:537–708) validates the cheques, generates an encrypted CSV, uploads via SFTP to Equity's host-to-host channel, and logs h2h_status updates. Petty-cash LPO payments in a bank file get stage = 'Paid' + the bank_file_number.

Cash / safe path: is_safe payment methods check the safe-ledger balance before the voucher is created (:2140) and raise a safe_withdrawal_request on approval; enable-open-cheques (:442) governs the blank-cheque workflow.

Display nuance: cheque/cash payments show as "paid" on issuance (status APPROVED); bank-transfer payments only show as "paid" once PROCESSED.

3.6 GL posting seams (double entry)

Event Debit Credit
Supplier invoice posted GIT (goods-in-transit) + Variance (if invoice≠GRN price) + VAT Input Creditors Control (supplier-specific or company default)
Credit note → supplier — Creditors Control (counterpart at original invoice)
Credit note → debtor — Debtors Control (one-sided; wa_debtor_trans −ve)
Payment voucher processed Creditors Control (+ WHT liability) Bank
Withholding tax payment WHT GL account Bank (+ wa_banktran)
VAT payment VAT liability Bank
Statutory payment (PAYE/NHIF/NSSF) Statutory liability Bank (+ wa_supp_trans)
GL payment (generic) Chosen GL account Bank

Creditors account selection: SupplierChartOfAccountService::getCreditorsAccountCodeForPosting() (supplier-specific), falling back to the company default. "Extensive GL posting" (ExtensiveGlPostingService::applySupplierInvoicePosting(), :2665–2683) posts per stock category when that feature is enabled — otherwise the single default posting at :2684–2701.

3.7 Statutory & tax payments (the AP tail)

The same voucher/approve rails carry statutory obligations, each with its own status (0=pending → 1=approved) and GL posting on approval: - Withholding tax — WithholdingTaxPaymentController (voucher) + WithholdingFilesController (aggregates WHT across bank files into wa_withholding_files per withholding_tax_types). Supplier subject to WHT via wa_suppliers.tax_withhold / professional_withholding. - VAT — VatPaymentController (wa_vat_payments): DR VAT liability / CR bank. - Statutory — StatutoryPaymentController (statutory_payments, payment_type = PAYE/NHIF/NSSF, optional penalty_amount). - Generic GL — GlPaymentController (gl_payments): DR any GL account / CR bank.

3.8 Advance payments

advance_payments (status Pending/Paid, ids from 10001) records prepayments to a supplier against an LPO. advance_payment_allocations later applies an advance to a specific wa_supp_trans invoice. Advances are themselves paid through a payment voucher (payable_type = 'advance'), closing the loop.

4. Tables touched & key data

Creditor ledger (core): - wa_supp_trans — THE supplier ledger (spelling verbatim; note misspelled journel_entry_id). One row per invoice / note / payment. Key cols: supplier_no, document_no, suppreference, trans_date, due_date, total_amount_inc_vat, allocated_amount, settled, pre_settled, withholding_amount, is_processed_withholding_tax, exempted_for_payment, manually_settled_at/reason/by, balancing_gl_account. Balance = total_amount_inc_vat − allocated_amount; settled=1 when balance < 1.0. - payment_voucher_items — polymorphic allocation (payable_id + payable_type), amount, vat_amount, withholding_tax_amount.

Invoice / bill sources: wa_supplier_invoices (+_items) [PO-based], supplier_bills (+_items) [non-PO], opening_balance_invoices, supplier_consumable_invoices, tyre_supplier_invoices, property_supp_trans (property mgmt, separate ledger).

Adjustments: financial_notes (+_items), financial_note_debtor_allocations, wa_supp_tran_credit_notes (junction: invoice ↔ credit-note demand).

Advances: advance_payments (status Pending/Paid, ids from 10001) + advance_payment_allocations (→ wa_supp_trans_id).

Payment instruments & files: payment_vouchers (status 0–3), payment_voucher_cheques (types normal/open/postdated; status issued/consumed/cleared/bounced; PDC + bounce fields), wa_bank_files (+_items), safe_withdrawal_requests.

Ledgers written on settlement: wa_supp_trans (payment rows), wa_bank_trans, wa_gl_trans.

Statutory: withholding_payment_vouchers, wa_withholding_files (+_items), withholding_tax_types, wa_vat_payments, statutory_payments (+_items), gl_payments.

Sign convention: debit / increase-in-payable = positive total_amount_inc_vat (invoice, debit note); credit / decrease = negative (credit note, payment). settled 0=open, 1=paid. Withholding threads across wa_supp_trans, payment_voucher_items, supplier_bills, financial_notes, advance_payments.

5. Interactions with other modules

  • ← Book 2 Ch9 (Goods Receiving) and ← Ch12 (Purchases): the GRN and PO are the source of the PO-based payable. supplier_invoice_process reads the GRN, closes the PO when fully invoiced, and links back via wa_grns.wa_supplier_invoice_id. (Ch12's model relations confirm the reverse seam: WaSuppTran/WaGlTran/AdvancePayment all hang off wa_purchase_order_id.)
  • → Book 4 (Finance / GL): every AP event posts to wa_gl_trans (creditors control, GIT, VAT input, WHT/VAT/statutory liabilities, bank). Bank-file settlement posts to wa_bank_trans. AP is a major feeder of the trial balance.
  • → Debtors (Book 1): supplier credit notes with affects_debtors=true cross into wa_debtor_trans / customer_credits — an unusual supplier↔customer bridge worth flagging to reviewers.
  • ↔ Petty cash / fuel / tyres / consumables / property: each has its own invoice table but settles through the same payment-voucher polymorphism — a strong argument that the voucher engine is the true AP hub.
  • → Bank integration: Equity host-to-host (SFTP + encrypted CSV) is a live external dependency for EFT.

6. Alternatives & variants

  • PO-based invoice (wa_supplier_invoices) vs non-PO bill (supplier_bills) — two front doors to the same ledger; both flow through payment vouchers.
  • Approval-workflow ON vs OFF for invoice posting (grn_pending_approval + TaskCenter vs direct suppliers-invoice___add).
  • Two-step voucher confirmation (confirm-details then approve-confirmation) — may be disabled per tenant.
  • Partial payment — allow-supplier-invoices-partial-payment setting.
  • Extensive vs default GL posting — per-stock-category vs single creditors posting.
  • Cheque (normal/open/postdated) vs EFT bank-file vs safe/cash — three settlement rails, tenant/account-driven.
  • Equity H2H — bank-specific integration; other banks presumably settle via manual/CSV export (unverified).
  • Specialised invoice tables (supplier_consumable_invoices, tyre_supplier_invoices, property_supp_trans) are recent (2025–2026 migrations) — likely feature-flagged per client.

7. Open questions to confirm

CODE-PROVEN (verified in source): - wa_supp_trans is the single creditor ledger; balance = total_amount_inc_vat − allocated_amount, settled flips under 1.0. - Voucher status machine 0/1/2/3 and the approve→ProcessVoucher→(cheque|bankfile|safe) settlement paths. - Polymorphic payment_voucher_items pays 9+ payable types through one engine. - Sign convention: DEBIT note +ve, CREDIT note −ve on the ledger. - GL posting map in §3.6 (GIT/Variance/VAT-input/Creditors on invoice; Creditors/WHT vs Bank on payment). - Equity host-to-host EFT via encrypted CSV over SFTP.

INFERENCE / to confirm with devs & users: - Which tenants run the approval workflow, two-step confirmation, partial payments, and extensive GL posting? (config, not code.) - Are the specialised invoice tables (consumable/tyre/property) live for any current client, or scaffolding? (recent migrations suggest early rollout.) - Exact due_date / payment-terms derivation at SupplierController.php:2537 — needs a focused read. - How non-Equity banks are paid (no H2H path was located). - Whether property_supp_trans is truly AP or a parallel mini-ledger for the property module. - The precise "confirm" business meaning (fraud check? bank-detail verification?) vs "approve".

8. Source references

Controllers (bizwiz/app/Http/Controllers/Admin/): - SupplierController.php — supplier_invoiced_list() :1797, supplier_invoice_order_details() :2014, supplier_invoice_process() :2334 (txn 2451–2721; WaSuppTran 2522–49; GL 2652–2703; PO close 2705–14; event 2718) - ProcessedInvoiceController.php — index :39, show :302, update :335, reverse :397 - OpeningBalanceInvoiceController.php — index :27, store :145 - FinancialNoteController.php — index :51, store :204, allocate :708, deallocate :1017, processDebtorAllocations :887–1001 - PaymentVoucherController.php — index :91, create :393, store :2021–2259 (alloc :2603, storeInvoiceItems :2871), approve :4616–4741, decline :4743, reverse :4786, confirm :4933, settlePaidInvoices :4964 - BankFilesController.php — index :42, create :127, store :193–287, sendToEquityBankH2H :537–708 - VoucherChequeController.php — index :29, store :438, clearPostdatedCheque :1080, bounce :1104, issueOpenCheque :1010 - OutgoingChequeVerificationController.php — index :37, verifyCheque :106, autoVerify :649 - WithholdingTaxPaymentController.php :29/150/317 · WithholdingFilesController.php :135 · VatPaymentController.php :28/122/172 · StatutoryPaymentController.php :35/128 · GlPaymentController.php :26/105/154

Actions: app/Actions/PaymentVoucher/ProcessVoucher.php :24, 73–112 (bank), 116–217 (WHT); ReverseVoucher.php :25; ReverseSupplierInvoice (referenced from ProcessedInvoiceController).

Models & migrations: - app/Model/WaSuppTran.php — migration 2023_09_08_134414_create_wa_supp_trans_table.php - app/PaymentVoucher.php :21–27 · app/PaymentVoucherItem.php (2024_02_27_031806) · app/PaymentVoucherCheque.php :21–28 (2024_02_27_055946, bounce fields 2025_10_21) - app/FinancialNote.php (2024_03_07_145405) · app/WaSupplierInvoice.php (2024_03_12_132845) - supplier_bills (2024_11_12_082741) · advance_payments (2024_06_20) + advance_payment_allocations (2024_06_24) - opening_balance_invoices (2025_03_13_095213) · app/Models/SupplierConsumableInvoice.php (2026_01_16_091841) · app/Models/TyreSupplierInvoice.php (2026_03_02_100200) · app/Models/PropertySuppTrans.php (2025_11_18_055058) · app/Models/WaSuppTranCreditNote.php (2025_08_19_153929)

Services: GlTransactionService, SupplierChartOfAccountService::getCreditorsAccountCodeForPosting(), ExtensiveGlPostingService::applySupplierInvoicePosting(), WaSuppTranOutstandingService::calculate(), TaskCenterService::assertCanAct(), NumberSeriesGeneratorService / getCodeWithNumberSeries().

Nav include (module boundary): bizwiz/resources/views/admin/includes/sidebar_includes/accounts_payable.blade.php.

Chapter 13 assembled from static analysis of the bizwiz Laravel monolith. Research recovered from three parallel code-tracing passes (creditor ledger schema, GRN→invoice posting, payment-voucher/cheque/EFT lifecycle) after the parent agent was interrupted. Flag anything that contradicts on-the-ground practice — §7 is the review instrument.