Banking

The Banking module (branded "Banking & Payments" in the sidebar) manages the bank accounts a Lubb ERP site collects and pays money through, imports/scrapes their transactions, and reconciles those lines against Payment Entries, Journal Entries and Paystack settlements. It also holds the Card Vault — Paystack's reusable card-charge tokens captured by storefront checkouts and invoice "Pay Now" flows — and their monthly auto-charge (debit order) enrollment. It's used by finance/admin staff doing the books; the FNB scrape and Paystack settings are further gated to a platform superuser.

What you can do

• Maintain a Bank Accounts register (name, bank, account number, currency, linked GL account, and FNB/Paystack flags) that every other banking screen scopes off.
• Maintain the same table under a second, non-technical Currencies view (account holder, branch/sort code, IBAN, SWIFT/BIC) — this is what actually prints on customer invoices/statements per currency.
• Browse a flat, cross-account Bank Transactions log with deposit/withdrawal/unreconciled stats and a manual "Create payment" bulk action.
• Run FNB Bank Reconciliation and Paystack Bank Reconciliation as two parallel worklists (same engine, scoped to accounts flagged is_fnb / is_paystack): import an OFX statement, auto-match lines, pull live transactions, create a Payment or Journal Entry per line, match a Paystack settlement payout, park a line to Suspense, or unallocate a previous match.
• Configure Recon Rules (keyphrase → ledger account, e.g. "UNPAID" → Bank Charges) and Auto-Match Aliases (a customer/supplier's bank narrative → their record) that the auto-matcher and worklist suggestions use — advisory only, never auto-posted for rules, but party aliases do drive auto-posted matches.
• Configure and trigger FNB Bank Sync (online-banking credentials, default account, one-shot scrape) from its own settings page, separate from the reconciliation grids.
• Configure Paystack gateway settings (public/secret key, currency, subaccount) that power both the settlement sync and the Card Vault's charges.
• Manage the Card Vault — every customer's saved Paystack card (masked brand/last4/expiry, source site, status), with the ability to revoke a card or toggle its monthly auto-charge (debit order) enrollment.

Common tasks

1. Set up a bank account for reconciliation Open Bank Accounts, add a row with the bank name, account number, currency and linked GL account, then tick the FNB and/or Paystack column depending on how its transactions will arrive. Only accounts flagged is_fnb appear in the FNB Bank Reconciliation scope selector, and only the one flagged is_paystack (with a GL account set) can be synced into or matched against Paystack settlements.

2. Import a bank statement and reconcile it On FNB Bank Reconciliation, pick the bank account from the scope selector, click "Import Statement" to upload an OFX file (duplicates are skipped automatically), then "Auto-match" to link lines to an existing Payment Entry, recognise the payer from the description, or apply a saved keyphrase rule. Anything left over can be handled per line: "Create Payment" or "Create Journal" from a row, or "Allocate to Suspense" to clear it from the worklist pending later reclassification. Auto-match also runs unattended every morning at 08:30.

3. Live-sync FNB transactions From Settings, save the FNB Bank Sync credentials (username, password, account number, default bank account); a platform superuser can then trigger a scrape from the FNB Bank Sync page or click "FNB Sync Trx" on the FNB Bank Reconciliation toolbar to pull new lines into the scoped account. It's a one-attempt operation — a failure (usually FNB's OTP/2FA gate) is surfaced as-is rather than retried, to avoid tripping the bank's fraud detection.

4. Sync and reconcile Paystack settlements Configure the site's Paystack keys under Settings, click "Sync Paystack Trx" on Paystack Bank Reconciliation to pull the last 30 days of successful transactions into the flagged Paystack account (also run automatically twice daily), then use "Match Settlement" on an FNB deposit line whose amount matches a settlement's net payout — this books the transfer out of the Paystack clearing account (debit FNB net, debit Paystack Fees, credit Paystack Clearing) and reconciles the line.

5. Fix a wrongly-matched line On either reconciliation worklist, a line already linked to a voucher shows "Unallocate" — this cancels the matched Payment/Journal Entry (reversing its GL and any invoice allocation) and unlinks the statement line so it can be re-matched correctly.

6. Enroll a customer's card for auto-charge A card lands in the Card Vault automatically the first time a customer completes a Paystack checkout or pays an invoice/statement online; a Debit Order signup checkout sets its auto_charge flag automatically. To enroll or unenroll a card by hand instead, open Card Vault and toggle "Auto-Charge Monthly" on the row — enrolled cards are then charged for the customer's full open balance the moment a Bill Run's invoices post.

Data model

• AccBankAccount — a bank account (name, bank, account number, currency, IBAN/SWIFT, linked GL account, is_fnb/is_paystack flags, last_scraped_at); surfaced as two grids (Bank Accounts, Currencies) over the same table.
• AccBankTransaction — one imported/scraped statement line (date, description, reference, amount, running balance, status unreconciled/reconciled/ignored, source fnb/ofx/csv/paystack/manual, and the matched voucher it was reconciled against).
• AccReconRule — a keyphrase-to-ledger-account rule that suggests (and, via Create Journal, pre-fills) how to book a recurring bank-only line with no invoice or party behind it.
• AccPartyAliasRule — a bank-narrative-to-Customer/Supplier alias so the auto-matcher can recognise a party whose statement narrative doesn't resemble their registered name; a hit both suggests and auto-posts a Payment Entry.
• CardVaultAuthorization (card_vault_authorizations) — a reusable Paystack card token plus masked metadata (brand, last4, expiry, bank), keyed by source site + email, with auto_charge gating the monthly debit-order sweep; lives in the shared "tc" (Cockpit) site database, since storefronts and the accounting app's own Pay Now/Charge Saved Card flows all write to one central vault.
• Relationship to Accounting: reconciling a line creates an AccPaymentEntry or AccJournalEntry against the Chart of Accounts (AccAccount), which posts to the same GLEntry spine every other financial report reads from; the Paystack clearing/fees accounts are ordinary GL accounts resolved (or auto-created) by name.
• Relationship to Subscriptions/Debtors: an auto-matched customer receipt that covers a Sales Order's balance converts that order into a submitted Invoice and raises its Activation; the debit-order sweep charges a customer's outstanding GL balance the moment a Bill Run posts.

Configuration & integrations

• FNB Bank Sync — online-banking username/password, account number and an optional proxy server, saved via its own settings endpoint (password never echoed back); the save and the scrape are both restricted to a platform superuser.
• Paystack — public key, secret key, default currency and subaccount, configured under Settings → Payments (secret key never returned by GET); this same configuration powers the settlement sync, the invoice/statement "Pay Now" and "Charge Saved Card" actions, and the Card Vault's debit-order sweep.
• Both integrations are read/written through dedicated settings services (fnb_bank_sync, paystack_settings) rather than being embedded in the reconciliation grids themselves — the grids only trigger the sync and show its results.

API reference

Most of Banking is generic grid CRUD under /api/v1/grid/{slug}/... (GET /data, POST /{slug}, PUT /{slug}/{row_id}, DELETE /{slug}/{row_id}, GET /stats, POST /action/{key} for toolbar/row buttons) for the acc-bank-accounts, acc-currencies, acc-bank-transactions, acc-recon-rules, acc-party-alias-rules and saved-cards grids. The reconciliation worklists (fnb-bank-reconciliation, paystack-bank-reconciliation) use the same action mechanism plus a handful of purpose-built endpoints under /api/v1/accounting:

• POST /accounting/bank/import-statement/{bank_account_id} — parse and import an uploaded OFX statement (deduped).
• POST /accounting/bank/auto-match/{bank_account_id} — run auto-match for one account.
• GET /accounting/bank/match-candidates/{txn_id} — vouchers that could clear a given statement line.
• GET /accounting/bank/payment-form-options/{txn_id} / POST /accounting/bank/create-payment/{txn_id} — options for, then submit, the Create Payment modal.
• GET /accounting/bank/journal-form-options/{txn_id} / POST /accounting/bank/create-journal/{txn_id} — options for, then submit, the Create Journal modal.
• POST /accounting/bank/reconcile/{txn_id} — manually reconcile a line against a chosen voucher.

FNB Bank Sync (/api/v1/fnb-bank-sync): GET /settings and PUT /settings (credentials, password withheld on read), GET /status (settings plus a reconciliation snapshot), POST /scrape (trigger a live pull).

Paystack settings (/api/v1/settings/paystack): GET "" / PUT "" (keys, secret withheld on read), POST /test (verify the configured credentials).

Card Vault (/api/v1/vault): POST /authorizations and POST /cards (machine-to-machine, storefront-facing, guarded by an X-Vault-Secret header) to upsert/query a customer's saved cards; GET /manage/cards and DELETE /manage/cards/{id} (authenticated, platform-superuser-only) for the admin-facing masked list and soft-delete used behind the Card Vault grid.