WALLET MODULE
The Leaseora Wallet module is the financial transaction layer that connects client payments, landlord collections, property-level balances, lender activity, payouts, virtual accounts and government remittances. It supports individual users and multi-property organisations while maintaining transaction status, audit history, security controls and reporting.
|
LEASEORA WALLET MODULE Detailed User and Technical Operations Guide Create • Fund • Pay • Transfer • Withdraw • Approve • Monitor • Secure • Analyse • Reconcile |
For real estate companies, landlords, finance teams, clients, lenders, enterprise approvers, administrators and government wallet users
Version 1.0 | July 2026
|
|
Purpose of this guide This guide explains how to configure and operate the Leaseora Wallet module from automatic wallet creation through top-ups, payment methods, rent and service payments, transfers, scheduled payments, withdrawals, landlord payouts, enterprise approvals, multi-currency, fraud controls, AI insights, administration and audit. It combines user procedures with the technical models, controllers, services, jobs, events and notifications supplied for the module. |
1 Purpose, Audience and Scope
The Leaseora Wallet module is the financial transaction layer that connects client payments, landlord collections, property-level balances, lender activity, payouts, virtual accounts and government remittances. It supports individual users and multi-property organisations while maintaining transaction status, audit history, security controls and reporting.
|
Item |
Description |
|
Primary users |
Real estate companies, landlords, finance teams, clients/tenants, lenders, enterprise approvers, platform administrators and government agencies. |
|
Core scope |
Wallet creation, settings, top-up, saved methods, virtual accounts, rent and service payments, transfers, scheduled payments, withdrawals, payouts, analytics, multi-currency, fraud, risk, audit and administration. |
|
Related Leaseora modules |
Lease Management, Property Purchases, Land Management, We Build For You, Property Development, Accounting, Mortgage and Government Tax. |
|
Terminology |
This guide uses Client/Tenant where the technical implementation uses Tenant. Wallet means the user’s stored-value account and its transaction ledger. |
|
Operational boundary |
Leaseora records and processes configured wallet actions. Settlement timing, gateway availability, banking rules, KYC/AML, tax and regulatory obligations depend on the relevant provider and jurisdiction. |
|
|
Financial control principle A displayed balance should be supported by confirmed WalletTransaction records. Manual balance adjustment, force transaction, payout approval and wallet unfreeze are sensitive administrative actions and should require authorised review. |
Wallet types in the module
|
Wallet type |
Purpose |
Typical owner |
|
User Wallet |
Primary balance, top-ups, payments, transfers and withdrawals. |
Landlord, client/tenant or other registered user. |
|
PropertyWallet |
Property-level financial tracking and analytics. |
A specific managed property. |
|
LenderWallet |
Financing marketplace funds and lender transactions. |
Registered lender. |
|
Government Agency Wallet |
Receives configured government tax or remittance flows. |
Government tax agency. |
|
Enterprise consolidated view |
Aggregates multiple property and organisational balances. |
Large real estate company. |
2 Complete Wallet Lifecycle and Navigation
Figure 1. Leaseora Wallet end-to-end lifecycle
|
Menu area |
Primary purpose |
|
Wallet Dashboard |
Balance, recent transactions, payment methods, scheduled payments and wallet health. |
|
Top Up |
Add funds through gateway, saved card, SEPA or virtual account. |
|
Payments |
Pay rent, leases and supported platform services. |
|
Transfer |
Send funds to another Leaseora wallet. |
|
Withdraw / Payout |
Move wallet funds to a verified bank account. |
|
Payment Methods |
Manage saved cards and supported funding instruments. |
|
Transactions |
Search, filter, view, print and export wallet activity. |
|
Multi-Currency |
View balances and conversion rates and switch the primary currency where permitted. |
|
Security |
PIN, transaction limits, fraud alerts, risk indicators, 2FA and freeze status. |
|
Enterprise Wallet |
Multi-property consolidation, approval workflows, bulk payments and audit. |
|
Admin Wallet Management |
Platform monitoring, adjustments, audit, risk, currencies, regions and reports. |
3 Roles, Permissions and Segregation of Duties
|
Role |
Typical responsibility |
Control point |
|
Wallet User |
Top up, pay, transfer, manage methods and withdraw within permitted limits. |
PIN, 2FA, limits and wallet status. |
|
Landlord Finance Officer |
Review income, transactions, property performance and payouts. |
Should not approve own high-value exception. |
|
Enterprise Initiator |
Creates single or bulk transaction requests. |
Cannot be sole approver where segregation is required. |
|
Enterprise Approver |
Approves or rejects pending transactions. |
Approval authority and threshold should be defined. |
|
Payout Administrator |
Reviews payout details, exceptions and manual intervention. |
Bank verification and audit evidence required. |
|
Fraud/Risk Officer |
Investigates alerts and recommends freeze or unfreeze. |
Investigation record should support the decision. |
|
Wallet Administrator |
Manages currencies, platform settings, top-ups and wallet creation. |
Manual adjustments require restricted access. |
|
Auditor / Compliance |
Reviews transaction, payout, security and consent logs. |
Read-only access is preferred. |
|
Government Wallet User |
Reviews configured remittance and payout status. |
Restricted to government domain and authorised data. |
Recommended permission controls
· Use individual accounts and two-factor authentication where available.
· Restrict adjustBalance, deposit, forceTransaction, reconcileWallet, approvePayout, markPayoutCompleted, rejectPayout and unfreeze.
· Separate transaction initiation from approval for enterprise or high-value workflows.
· Restrict bulk payment upload and processing to trained finance staff.
· Use audit logs for every administrative balance or payout change.
· Review access when a staff member changes role or leaves the company.
4 Wallet Architecture and Core Records
|
Record |
What it stores |
Key control |
|
Wallet |
User, balance, currency, status, encrypted transaction PIN and freeze flag. |
Balance must reconcile to transaction history. |
|
WalletTransaction |
Every credit, debit, transfer, payment, withdrawal and adjustment. |
Unique reference and status are essential. |
|
WalletTopup |
Funding request, gateway, amount and verification result. |
Credit only after successful verification. |
|
PropertyWallet |
Property-level balance and performance. |
PropertyWalletUpdated event records changes. |
|
LenderWallet / LenderWalletTransaction |
Lender balances and movements. |
Use LenderWalletService. |
|
ScheduledWalletPayment |
Future or recurring wallet payment instruction. |
Due date, amount and funding availability. |
|
LandlordPayout / TenantPayout |
Outbound payout or withdrawal request and status. |
Bank verification and processing job. |
|
PayoutAudit |
History of payout decisions and changes. |
Retain for reconciliation and investigation. |
|
WalletRiskIndicator |
Health and risk signals per wallet. |
Review source and update time. |
|
WalletTransactionAudit |
Full wallet action and transaction audit. |
Exportable for authorised review. |
|
|
Balance is a controlled result Application code should not treat balance as an isolated number. Credits and debits should create WalletTransaction records, trigger the observer and preserve a traceable status and reference. |
5 Phase 1 - Wallet Creation and Initial Setup
|
STEP |
Automatic Wallet Creation Primary user: System / user registration |
Every eligible Leaseora user should receive a Wallet record during registration. LandlordWalletService@getOrCreateWallet ensures that a landlord wallet exists when required. The wallet currency is derived from the user country under the configured currency rules.
|
Field |
Meaning |
Operational check |
|
user_id / user_type |
Links the wallet to its owner. |
The owner must be correct and unique where required. |
|
balance |
Current available wallet balance. |
Should start at the approved opening value, normally zero. |
|
currency |
Primary wallet currency. |
Confirm the country-to-currency rule. |
|
status |
Active, Frozen or Suspended. |
Only Active wallets should transact. |
|
transaction_pin |
Encrypted PIN for authorisation. |
Never store or display in plain text. |
|
is_frozen |
Explicit transaction-blocking flag. |
Must be enforced by middleware. |
Automatic creation checks
|
☐ |
User has one correct primary wallet. |
|
☐ |
Default currency matches the user’s country or approved setting. |
|
☐ |
Wallet status is Active. |
|
☐ |
Balance is correct. |
|
☐ |
No PIN is exposed in logs or responses. |
|
STEP |
Configure Wallet Settings Primary user: Wallet user / administrator |
Open Wallet Settings to select the default currency preference, notification preferences, auto-collection options, transaction PIN and spending limits. Platform administrators can configure global limits, fees, currencies and gateway settings through WalletSettingsController.
|
Setting |
User purpose |
Administrative consideration |
|
Default currency |
Controls primary wallet display and supported transaction context. |
Currency switching rules and conversion history. |
|
Transaction PIN |
Authorises sensitive actions. |
Change, retry and lockout controls. |
|
Notifications |
Controls wallet event communication. |
Mandatory security notices may not be optional. |
|
Auto-collection |
Supports recurring collections where configured. |
Consent, mandate and failure handling. |
|
Spending limit |
Caps transaction value. |
High-value middleware may add extra checks. |
|
Allowed currencies |
Defines supported wallet currencies. |
Regional, gateway and compliance availability. |
|
Fees |
Defines configured service charges. |
Must be disclosed before confirmation. |
|
|
PIN and limits are security controls Changing a PIN or limit should be authenticated, logged and communicated. A user should see the applicable fee, amount, currency and recipient before confirming a wallet transaction. |
6 Phase 2 - Wallet Top-Up Overview
|
STEP |
Add Funds to the Wallet Primary user: Client/Tenant, landlord or authorised user |
Top-up converts an external funding source into wallet balance. The system creates a WalletTopup record, processes the selected method, verifies the result and then credits the wallet through a WalletTransaction.
Figure 2. Funding, wallet and outgoing money flow
|
Method |
Best suited for |
Confirmation requirement |
|
Payment gateway |
One-time online top-up. |
Gateway API verification and valid transaction reference. |
|
Saved/tokenised card |
Repeat card top-ups. |
Valid token, 3DS where required and gateway confirmation. |
|
SEPA direct debit |
Supported European bank debit. |
Valid mandate and settlement confirmation. |
|
Virtual account |
Bank transfer to a dedicated account. |
Provider webhook or verified incoming transfer. |
|
Admin manual deposit |
Controlled exception or correction. |
Authorised admin action, reason and audit record. |
|
|
Do not credit on redirect alone A user returning from a payment page is not sufficient evidence of payment. The gateway or provider must verify the transaction before the wallet is credited. |
7 Gateway Top-Up Procedure
Supported gateway top-up flows use Flutterwave, Stripe, Revolut, Paystack or Squad according to configuration and country availability.
1. Open the top-up form and enter the amount.
2. Select an available payment gateway.
3. Review currency, fees, total debit and expected wallet credit.
4. Confirm the transaction and complete the gateway payment session.
5. Return to Leaseora through the success or failure callback.
6. Allow the system to verify the transaction with the gateway API.
7. On success, create the wallet credit transaction and update the balance.
8. Send WalletCreditedNotification, WalletBalanceUpdated and the top-up invoice where configured.
9. On failure, retain a failed or cancelled top-up record without crediting the wallet.
|
Controller action |
Purpose |
|
showTopupForm / landlordTopupForm |
Display the correct top-up interface. |
|
topup / landlordTopup / processTopUp |
Create and initiate the funding request. |
|
tenantTopupCallbackSuccess / landlordTopupCallbackSuccess |
Receive the return from a successful user flow. |
|
tenantTopupCallbackFailed / landlordTopupCallbackFailed |
Record a failed or cancelled flow. |
|
verifyTopUp |
Confirm transaction status with the provider. |
|
|
Top-up reconciliation Finance should reconcile the wallet credit, gateway transaction, gateway fee, settlement and top-up invoice. A successful wallet credit can precede provider settlement, but both states should remain visible. |
8 Saved Card and Tokenisation Procedure
Saved cards reduce repeated entry of card details by storing a gateway token rather than raw card information in Leaseora. Tokenisation and card charging remain provider-dependent.
|
Action |
Purpose |
Control |
|
initializeCardTokenization |
Starts token creation with a gateway. |
Use secure redirect or provider component. |
|
handleCardTokenizationCallback |
Receives tokenisation outcome. |
Verify callback authenticity. |
|
checkTokenizationStatus |
Checks whether the method is usable. |
Do not display unusable tokens. |
|
chargeCardDirect / processDirectCard |
Charges the saved token. |
Show amount and require authorisation. |
|
authorizeCardPayment / authorizeDirectCard |
Completes 3DS or additional authorisation. |
Do not credit before final success. |
|
chargeSavedPaymentMethod |
Uses the selected saved method. |
Confirm ownership and default status. |
Gateway-specific mobile tokenisation
· initializeSquadTokenization
· initializeStripeTokenization
· initializePaystackTokenization
· initializeFlutterwaveTokenization
|
|
Do not store raw card data Leaseora should store provider tokens and safe metadata only. Card-number, CVV and sensitive authentication data handling must follow the provider and applicable payment security rules. |
9 SEPA Direct Debit and Mandate Management
WalletSepaController manages SEPA wallet funding where available. The client can view a mandate timeline and receive expiry or renewal notifications.
1. Confirm the user’s country and SEPA eligibility.
2. Collect the required bank and mandate information using the approved flow.
3. Display mandate terms and obtain the required authorisation.
4. Save the mandate reference and status.
5. Initiate the debit under the configured collection schedule.
6. Credit the wallet only under the approved settlement or risk policy.
7. Monitor mandate expiry and send TenantSepaExpiryNotification or mandate renewal notice.
8. Handle rejection, return or mandate cancellation through the configured process.
|
|
SEPA timing differs from card funding Direct debit can have delayed settlement, return and chargeback windows. The deployed wallet should clearly define when funds become available and how a later return is handled. |
10 Virtual Account Funding
A virtual account gives the user a dedicated bank-account reference. Incoming transfers can be attributed to the correct wallet without manual narration matching.
|
Component |
Role |
|
getVirtualAccount |
Returns the current dedicated account details. |
|
createVirtualAccount |
Requests a new account from the configured provider. |
|
EmbedlyVirtualAccountService |
Provisions and manages Embedly-backed accounts. |
|
FlutterwaveVirtualAccountService |
Provisions and manages Flutterwave-backed accounts. |
|
UserVirtualAccount / DepositAccount |
Stores account identity and deposit relationship. |
|
Provider webhook / verification |
Confirms incoming transfer and credits the wallet. |
Virtual account controls
|
☐ |
Account belongs to the correct user. |
|
☐ |
Provider status is active. |
|
☐ |
Displayed bank name, account number and beneficiary are correct. |
|
☐ |
Incoming transfer has a unique provider reference. |
|
☐ |
Duplicate webhooks cannot credit the wallet twice. |
|
☐ |
Returned or reversed transfer handling is defined. |
11 Top-Up Administration, Invoices and Exports
WalletTopupController gives authorised administrators a platform-wide view of top-ups and related invoices.
|
Action |
Administrative use |
|
index |
View all top-up records and statuses. |
|
invoices |
View top-up invoices. |
|
exportTopups |
Export top-up data. |
|
exportInvoices |
Export invoice data. |
|
getInvoiceStats |
Review invoice totals and trends. |
|
getFilteredInvoices |
Filter invoices by date, status, user or other configured criteria. |
|
|
Admin view is not a reason to edit provider truth When a top-up status differs from provider records, investigate the reference, verification and webhook logs before making any balance adjustment. |
12 Phase 3 - Saved Payment Methods and Bank Accounts
|
STEP |
Manage Saved Payment Methods Primary user: Wallet user |
Users can add, list, set a default and remove available payment methods. The wallet should present methods based on country, gateway and account eligibility.
|
Action |
Purpose |
|
getAvailablePaymentMethods |
Lists methods available for the user country. |
|
getPaymentGatewayForCountry |
Selects the configured gateway for the country. |
|
getCountryCode |
Normalises country information. |
|
addPaymentMethod / storePaymentMethod |
Saves a new provider-backed method. |
|
setDefaultPaymentMethod |
Sets the preferred funding method. |
|
deletePaymentMethod / removePaymentMethod |
Removes a saved method where permitted. |
|
|
Removing a payment method Do not remove a payment method that is required by an active mandate, scheduled payment or in-progress transaction without a defined replacement and user warning. |
13 Withdrawal Bank Accounts
TenantWalletController and Mobile\WalletController manage bank accounts used for withdrawal. Users can add, remove and select a primary account.
|
Action |
Purpose |
Control |
|
getBanksForCountry / getBankList |
Returns supported banks. |
Use current provider list. |
|
storeBankAccount / addBankAccount |
Adds the bank destination. |
Verify account owner and details. |
|
verifyAccountNumberAjax / verifyBankAccount |
Confirms account number with provider. |
Do not rely on user-entered name alone. |
|
setPrimaryBankAccount / setDefaultBankAccount |
Selects default withdrawal destination. |
Require authentication. |
|
destroyBankAccount / removeBankAccount |
Removes a bank account. |
Check pending payouts first. |
|
|
Verified destination only Withdrawals should be sent only to a verified bank account permitted for the user and jurisdiction. Any change to the primary account should be logged and notified. |
14 Phase 4 - Pay Rent, Lease and Platform Services
|
STEP |
Pay Rent from Wallet Primary user: Client/Tenant |
The client selects Pay with Wallet on the rent payment screen. CurrencyService converts the amount if the wallet and property currencies differ. FeeCalculationService calculates the service fee, the wallet is debited and the landlord payout process begins.
1. Confirm the active lease and outstanding rent payment.
2. Display the property currency, wallet currency, exchange rate, fee and total debit.
3. Check wallet status, balance, PIN, transaction limit and high-value requirements.
4. Deduct the authorised amount from the wallet.
5. Create the rent/payment record and WalletTransaction.
6. Create LandlordPayout and dispatch ProcessLandlordPayout.
7. Update the lease payment schedule.
8. Provide payment confirmation and receipt.
9. Handle payout failure separately from the confirmed client payment according to the configured policy.
|
STEP |
Pay Other Leaseora Services Primary user: Client/Tenant |
Mobile\WalletController@payService supports wallet payments for property purchase deposits, We Build For You instalments, land-sale instalments and other configured services. The originating module should receive the payment result and update its own record.
|
Service example |
Required linked record |
|
Property purchase deposit or balance |
SalesApplication / property purchase record. |
|
We Build For You instalment |
WeBuildTenantBooking and payment-plan item. |
|
Land sale instalment |
LandSale and LandPaymentInstallment. |
|
Property development booking |
PropertyDevelopmentTenantBooking / payment plan. |
|
Utility or other service |
Service or invoice record. |
|
STEP |
Pay an Active Lease Through Paylease Primary user: Client/Tenant |
WalletController@paylease provides a dedicated lease-payment action. Confirm the lease, due amount, wallet debit, fee and schedule update before final confirmation.
|
|
Cross-module consistency A successful wallet debit must update the originating Leaseora module. A wallet transaction without the corresponding rent, land, purchase or development payment record creates reconciliation risk. |
15 Scheduled Wallet Payments
|
STEP |
Create and Process Recurring Payments Primary user: Client/Tenant and system scheduler |
ScheduledWalletPayment stores recurring instructions such as paying rent on the first day of each month. ProcessScheduledWalletPayments selects due instructions and attempts payment.
|
Schedule field |
Purpose |
|
User and wallet |
Identifies the payer. |
|
Linked service / lease |
Identifies what is being paid. |
|
Amount and currency |
Defines the obligation. |
|
Frequency / next run |
Determines when processing occurs. |
|
Payment method |
Wallet balance or configured permitted method. |
|
Status |
Active, paused, completed or failed where configured. |
|
Failure count / last result |
Supports retry and user notification. |
|
☐ |
User has authorised the schedule. |
|
☐ |
Amount or rule is clear. |
|
☐ |
Wallet has sufficient balance or failure handling is defined. |
|
☐ |
The schedule does not duplicate another auto-collection method. |
|
☐ |
User can review, pause or cancel where permitted. |
|
☐ |
Every run creates a result and transaction reference. |
|
|
Scheduled payment is not guaranteed payment The scheduler should record insufficient funds, frozen wallet, expired mandate, limit failure or provider error and notify the user instead of silently missing the payment. |
16 Phase 5 - Wallet-to-Wallet Transfers
|
STEP |
Transfer Funds to Another Leaseora Wallet Primary user: Landlord or authorised wallet user |
The sender selects a recipient, amount and purpose, reviews a payment preview and confirms using the required transaction authorisation. Different wallet currencies can trigger conversion.
1. Find or identify the correct recipient wallet.
2. Enter the transfer amount and purpose.
3. Preview sender debit, recipient credit, exchange rate and fee.
4. Validate sender balance, wallet status, PIN and limits.
5. Create a single transfer reference.
6. Debit the sender wallet and credit the recipient wallet atomically.
7. Create WalletTransaction records for both sides.
8. Fire WalletTransactionCreated and WalletUpdated events.
9. Provide receipts and update both histories.
|
|
Atomic transfer control The transfer must not debit one wallet without crediting the other. Failure handling should reverse or roll back the complete operation under one reference. |
17 Phase 6 - Client/Tenant Withdrawals
|
STEP |
Withdraw Wallet Funds to a Bank Account Primary user: Client/Tenant |
The client selects a verified bank account, enters the amount and submits a withdrawal. The system creates a pending WalletTransaction and TenantPayout, then dispatches ProcessTenantPayoutJob.
1. Open the withdrawal form and review available balance.
2. Select an existing verified bank account or add and verify a new account.
3. Enter the withdrawal amount.
4. Review fees, limits, expected bank credit and processing status.
5. Authorise with transaction PIN and additional verification where required.
6. Create the pending wallet transaction and TenantPayout.
7. Reserve or deduct the amount according to the configured payout policy.
8. Dispatch ProcessTenantPayoutJob.
9. Send WalletWithdrawalNotification and WalletWithdrawalConfirmation.
10. Update final status to completed, failed, rejected or cancelled and reconcile the balance.
|
User action |
Controller support |
|
Open form |
showWithdrawForm / getWithdrawFormData. |
|
Get bank options |
getWithdrawBanks / getWithdrawalBanks. |
|
Verify account |
verifyWithdrawAccount / verifyWithdrawalAccount. |
|
Submit withdrawal |
withdraw / initiateWithdrawal. |
|
Review history |
withdrawalHistory / getWithdrawalHistory. |
|
|
Pending withdrawal balance treatment The deployed system should define whether a pending withdrawal reduces available balance immediately or creates a reserved amount. This must prevent double spending. |
18 Landlord Withdrawal and Automated Payout Rules
|
STEP |
Withdraw or Auto-Payout Landlord Funds Primary user: Landlord / finance team |
Landlord withdrawals use the landlord payout flow. AutomatedPayoutRule can initiate a payout when configured conditions are met, such as balance exceeding a threshold.
|
Rule / action |
Purpose |
Control |
|
Manual withdrawal |
Landlord requests a chosen amount. |
Verified destination and available balance. |
|
Threshold rule |
Payout when balance exceeds a configured value. |
Minimum retained balance and frequency. |
|
Scheduled rule |
Payout on a defined schedule. |
Avoid conflict with pending liabilities. |
|
ProcessLandlordPayout / Job |
Executes the transfer. |
Retries and failure visibility. |
|
PayoutAudit |
Records decision and status history. |
Retain immutable evidence. |
|
|
Automated payout rules need treasury review Automatic withdrawal may reduce liquidity needed for refunds, maintenance or future payments. The company should approve thresholds and retained balances. |
19 Payout Review, Approval and Exception Handling
|
Action |
Purpose |
|
getPayoutDetails |
View amount, destination, gateway, references and status. |
|
approvePayout |
Approve a pending payout where admin approval is required. |
|
markPayoutCompleted |
Record a completed manual or externally confirmed payout. |
|
rejectPayout |
Reject and record the reason. |
|
getPayoutStats |
Review payout totals and statuses. |
|
getPayoutChartData |
Visualise payout trends. |
|
requestPayout / cancelPayout |
Mobile request and cancellation where permitted. |
|
getPayoutHistory |
Review historical payouts. |
Payout statuses to manage
|
Status |
Meaning |
Required follow-up |
|
Pending |
Request created but not processed. |
Check approval, balance and destination. |
|
Processing |
Job or provider is handling the payout. |
Monitor provider reference. |
|
Completed |
Provider or authorised admin confirms success. |
Reconcile bank and wallet. |
|
Failed |
Processing failed. |
Preserve funds and retry or resolve. |
|
Rejected |
Authorised approver declined. |
Release any reserved amount. |
|
Cancelled |
User or admin cancelled before completion. |
Confirm no provider transfer occurred. |
|
Manual intervention |
Automation cannot complete. |
ManualPayoutRequired alerts admin. |
|
|
Status changes affect balances Every failure, rejection or cancellation must use a defined balance-release or reversal process. Administrative status editing alone is not sufficient. |
20 Phase 7 - Landlord Wallet Dashboard
|
STEP |
Use the Landlord Wallet Overview Primary user: Landlord / finance manager |
LandlordWalletController provides portfolio, income, expense, multi-currency, insights, reports, fraud, security and transaction views. LandlordWalletService supplies wallet statistics and financial summaries.
|
Dashboard area |
Management question |
|
Portfolio overview |
What is the wallet position across all properties? |
|
Rental income tracking |
How much rent was collected by property and period? |
|
Expense management |
What wallet-funded expenses were recorded? |
|
Multi-currency view |
What balances and activity exist by currency? |
|
AI insights |
What cash-flow or health issues require attention? |
|
Financial reports |
How did inflows and outflows perform in the selected period? |
|
Category analytics |
Which transaction categories drive spending or income? |
|
Fraud alerts |
Are there unresolved suspicious patterns? |
|
Security dashboard |
Are 2FA, limits and freeze states appropriate? |
|
Needs attention |
Which payments, payouts or exceptions require action? |
Key LandlordWalletService outputs
· getPortfolioSummary
· getRentalIncomeSummary
· getPropertyRentBreakdown
· getExpenseSummary
· getMultiCurrencySummary
· predictCashFlow
· getFinancialHealthScore
· getCategoriesSummary
· getFormattedBalance
· getWalletStatistics
· getPropertyPerformance
· getBulkPaymentStatistics
· needsAttention
21 Landlord Bulk Payments
|
STEP |
Upload and Process a Bulk Payment Batch Primary user: Landlord finance team |
Bulk payments allow the company to upload multiple payment instructions using a controlled CSV or Excel template.
1. Download the current bulk payment template.
2. Complete required recipient, amount, currency, purpose and reference fields.
3. Remove blank rows, duplicates and unsupported values.
4. Upload the file and review validation results.
5. Correct invalid rows before processing.
6. Confirm total amount, fees and available balance.
7. Obtain approval where required.
8. Process the batch.
9. Review successful, failed and pending rows.
10. Reconcile the batch total and export the result.
|
|
Never process an unchecked spreadsheet A valid file format does not mean the payment instructions are correct. Finance should review recipients, totals, duplicate references and approval evidence. |
22 Phase 8 - Enterprise Wallet Overview
|
STEP |
Use the Multi-Property Enterprise Dashboard Primary user: Enterprise finance and management |
EnterpriseWalletController supports multi-property views, consolidated financials, transaction approval, bulk payments and audit across a large real estate organisation.
Figure 3. Enterprise wallet approval and bulk payment flow
|
Capability |
Purpose |
|
multiProperty |
Shows balances and activity by property. |
|
multiPropertyConsolidation |
Provides consolidated financial view. |
|
consolidateFinancials |
Runs the configured consolidation process. |
|
exportConsolidated |
Exports consolidated data. |
|
getStatistics |
Provides enterprise wallet metrics. |
23 Enterprise Approval Workflows
|
STEP |
Create and Apply Multi-Level Approval Primary user: Enterprise administrator and approvers |
Approval workflows define who must approve a wallet transaction before processing. They can vary by amount, transaction type, property, department or configured rule.
|
Workflow element |
Example |
|
Transaction threshold |
Payments above £25,000 require two approvals. |
|
Initiator role |
Finance officer creates the request. |
|
Approver level 1 |
Property or department manager. |
|
Approver level 2 |
Finance director or executive. |
|
Rejection rule |
Record reason and return to initiator. |
|
Expiry / escalation |
Notify or reassign after a defined period. |
|
Audit record |
Store every decision, user and timestamp. |
|
|
Example currency The £25,000 amount is an illustrative workflow threshold. Each company should define thresholds in its operating currency and policy. |
1. Create the workflow and define scope.
2. Add approval levels and authorised roles.
3. Define thresholds and escalation.
4. Test approval, rejection and cancellation.
5. Publish the workflow.
6. Review pending transactions regularly.
7. Export audit evidence when required.
24 Enterprise Bulk Payments and Status
|
STEP |
Create, Approve and Process Enterprise Batches Primary user: Enterprise finance team |
Enterprise bulk payments use upload, create, process and status actions. The batch should remain pending until its validation and approval conditions are met.
|
Batch stage |
Control |
|
Draft / uploaded |
File retained but not executable. |
|
Validated |
Rows, currencies, accounts and totals checked. |
|
Pending approval |
Workflow decision outstanding. |
|
Approved |
Ready for processing. |
|
Processing |
Execution in progress. |
|
Partially completed |
Some rows succeeded and others require attention. |
|
Completed |
All expected results finalised. |
|
Rejected / cancelled |
No further processing permitted. |
25 Enterprise Audit Trail
|
STEP |
Review and Export Enterprise Wallet Audit Primary user: Enterprise auditor / management |
The enterprise audit view records transaction creation, validation, approval, rejection, processing, change and export. Audit charts and detailed records can be exported as PDF, CSV or Excel.
|
☐ |
Initiator identity is recorded. |
|
☐ |
Approver identities and sequence are recorded. |
|
☐ |
Original amount and later changes are visible. |
|
☐ |
Reason for rejection or override is present. |
|
☐ |
Batch file and processing result can be traced. |
|
☐ |
Payout and provider references are available. |
|
☐ |
Exports are restricted and logged. |
26 Phase 9 - Client/Tenant Wallet Dashboard
|
STEP |
Review Balance, Activity and Health Primary user: Client/Tenant |
TenantWalletController@dashboard and Mobile\WalletController@index provide current balance, currencies, recent transactions, upcoming scheduled payments, saved methods and wallet health.
|
Dashboard item |
What the client sees |
|
Balance |
Available wallet amount by currency. |
|
Recent transactions |
Top-ups, payments, transfers and withdrawals. |
|
Scheduled payments |
Upcoming automatic wallet actions. |
|
Payment methods |
Saved cards, bank instruments and default method. |
|
Detailed statistics |
Credits, debits, payments and other totals. |
|
Wallet trends |
Spending and balance movement over time. |
|
Transaction analytics |
Category, type and period analysis. |
|
Wallet health score |
System-generated indicator based on wallet behaviour. |
|
|
Health score is informational The score should not be presented as a guaranteed measure of financial reliability. Users should be able to understand the factors used where supported. |
27 Phase 10 - Transactions, Receipts and Statements
|
STEP |
View and Export Wallet Transactions Primary user: All authorised wallet users |
WalletController and Mobile\WalletController provide transaction history, status, detail and receipts. WalletTransactionObserver reacts to transaction creation or update and supports events, notifications and audit.
|
Action |
Use |
|
transactions / transactionHistory |
Paginated and filtered transaction list. |
|
getTransactionStatus |
Checks one transaction state. |
|
getTransactionDetails |
Shows amount, type, reference, parties, gateway and status. |
|
transactionReceipt |
Displays or downloads the receipt. |
|
export / exportAllData |
Exports wallet data. |
|
exportTransactionsCsv |
CSV transaction export. |
|
exportTransactionsPdf |
PDF statement or transaction export. |
|
exportTransactionsExcel |
Excel transaction export. |
|
printStatement / print |
Printable wallet statement. |
|
generateWalletReport |
Comprehensive wallet report. |
Transaction detail checklist
|
☐ |
Unique transaction reference. |
|
☐ |
Type and direction. |
|
☐ |
Original amount and currency. |
|
☐ |
Converted amount and exchange rate where applicable. |
|
☐ |
Fee amount. |
|
☐ |
Sender and recipient or service record. |
|
☐ |
Created, processed and completed timestamps. |
|
☐ |
Gateway or payout reference. |
|
☐ |
Current status and failure reason if applicable. |
|
|
Receipt does not replace settlement evidence A wallet receipt confirms the platform record. Bank or provider settlement may still need reconciliation for top-ups and payouts. |
28 Transaction Categories and Spending Analytics
|
STEP |
Create and Use Wallet Categories Primary user: Wallet user / administrator |
WalletCategory and WalletTransactionCategory organise wallet activity into categories such as Rent Income, Maintenance and Utilities. Categories improve reporting but should not change the original transaction type.
|
Category action |
Purpose |
|
Create / store |
Adds a custom category. |
|
Edit / update |
Changes category label or settings. |
|
Destroy |
Removes a category subject to linked transaction rules. |
|
Analytics |
Shows category totals and trends. |
|
Reset spending |
Resets calculated category spending where supported. |
|
Admin category management |
Maintains platform-wide category vocabulary. |
|
|
Category is classification, not accounting entry Changing a category should not change amount, currency, payment status or linked Leaseora service record. |
29 Phase 11 - Multi-Currency Wallet Operation
|
STEP |
View, Convert and Switch Wallet Currency Primary user: Wallet user / finance team |
The wallet can display country-based wallets, current rates, conversion and currency history. HasWalletCurrencyConversion provides shared conversion behaviour to applicable controllers.
|
Action |
Purpose |
Control |
|
getDefaultCurrencyForCountry |
Determines default currency. |
Country mapping must be maintained. |
|
convertCurrency |
Converts an amount. |
Display rate, spread and timestamp. |
|
getCurrencyRates |
Returns current rates. |
Data source and fallback required. |
|
getExchangeRateHistory |
Shows historical rate movement. |
Date and source must be clear. |
|
switchWalletCurrency |
Changes the primary wallet currency where permitted. |
Confirm conversion treatment and history. |
|
getCurrencyHistory |
Shows previous wallet currency changes. |
Retain audit trail. |
|
getWalletsByCountry / countryWallets |
Lists wallet balances by country or currency. |
Respect user access. |
|
|
A currency switch is not a label change Production rules must define whether switching converts the existing balance, creates a new currency balance or only changes display preference. The user should receive WalletCurrencyChangeConfirmation. |
30 Currency Administration and FX Revenue
WalletCurrencyAdminController manages exchange rates, live-rate updates, markup/spread and FX revenue monitoring.
|
Administrative action |
Purpose |
|
index |
Currency dashboard. |
|
rates |
View all configured exchange rates. |
|
updateRates |
Apply approved rate updates. |
|
liveRates |
Fetch external rates. |
|
updateMarkupSettings |
Configure FX markup or spread. |
|
revenueMonitor |
Review revenue attributable to conversion markup. |
|
☐ |
Rate source is approved. |
|
☐ |
Last update time is visible. |
|
☐ |
Markup is disclosed before transaction confirmation. |
|
☐ |
Rounding rules are consistent. |
|
☐ |
Fallback rate policy is documented. |
|
☐ |
FX revenue reconciles to transaction data. |
31 Phase 12 - Wallet Security Controls
|
STEP |
Use the Wallet Security Dashboard Primary user: Landlord / wallet user / security staff |
WalletSecurityController brings together fraud alerts, patterns, investigations, limits, IP logging, audit logs, 2FA status and security recommendations.
Figure 4. Wallet security, risk and AI intelligence
|
Control |
Purpose |
|
Transaction PIN |
User authorisation for wallet actions. |
|
Two-factor status |
Additional identity verification. |
|
validateTransactionLimit |
Checks amount against permitted limits. |
|
HighValueWalletTransaction middleware |
Applies enhanced checks for large transactions. |
|
logTransactionIp |
Records transaction network information. |
|
EnsureWalletNotFrozen middleware |
Blocks transactions when wallet is frozen. |
|
auditLogs |
Provides security and action history. |
|
recommendations |
Shows configured security improvements. |
|
|
Sensitive security data IP addresses, fraud indicators and authentication status are sensitive. Access should be restricted and retained under an approved security and privacy policy. |
32 Fraud Detection and Investigation
|
STEP |
Review Fraud Alerts and Patterns Primary user: Fraud/Risk team |
PropertyWalletFraudService analyses wallet activity and WalletFraudAlerts provides a real-time alert component. Alerts can be reviewed by wallet users where appropriate and by platform administrators.
|
Action |
Purpose |
|
fraudAlerts |
Lists unresolved or historical alerts. |
|
fraudPatterns |
Shows detected pattern groups. |
|
investigate / investigateFraudAlert |
Opens an investigation. |
|
getFraudAlertDetails |
Shows transactions, factors and history. |
|
markFraudAlertAsFalsePositive |
Closes an incorrect alert with reason. |
|
getFraudStatistics |
Provides aggregate alert metrics. |
|
exportFraudAlertsReport |
Exports authorised fraud information. |
Investigation workflow
1. Review the alert reason, score and affected transactions.
2. Confirm wallet owner, devices, IPs, amounts, recipients and timing.
3. Check related top-ups, transfers and withdrawals.
4. Freeze the wallet if required under policy.
5. Contact the user through an approved secure channel.
6. Record evidence and decision.
7. Escalate confirmed fraud or compliance concerns.
8. Mark false positives with an explanation.
9. Unfreeze only after authorised approval.
33 Wallet Freeze and Unfreeze
|
STEP |
Freeze or Restore a Wallet Primary user: Administrator / fraud authority |
A frozen wallet is prevented from transacting through EnsureWalletNotFrozen. WalletFrozenAlert is fired when a wallet is frozen due to suspected fraud or security concern.
|
Action |
Expected behaviour |
|
toggleFreeze |
Changes the wallet freeze state where the user has authority. |
|
freezeMultipleWallets |
Applies freeze to multiple wallets in a controlled admin action. |
|
WalletFrozenAlert |
Creates or distributes the freeze alert. |
|
unfreeze |
Restores transaction capability after approval. |
|
Audit log |
Records who, when and why. |
|
|
Freeze does not remove funds Freezing should block outgoing and other configured actions without deleting balance or transaction history. The exact treatment of incoming credits and scheduled payments must be confirmed. |
34 Phase 13 - Wallet Health Score and Risk Analysis
|
STEP |
Review Wallet Health Scores Primary user: User, landlord and risk administrators |
CalculateWalletHealthScore and the CalculateWalletHealthScores command produce a score using payment consistency, fraud history, balance trends and transaction patterns. WalletRiskIndicator stores risk signals.
|
Factor |
Potential interpretation |
|
Payment consistency |
Regular successful obligations may support a healthier score. |
|
Fraud history |
Confirmed or unresolved fraud can increase risk. |
|
Balance trend |
Frequent shortfalls or unstable balance can affect the indicator. |
|
Transaction pattern |
Unusual velocity, recipients or amounts may create risk signals. |
|
Payout behaviour |
Repeated failures or account changes may require review. |
|
STEP |
Run Platform-Wide Risk Analysis Primary user: Administrator / risk team |
WalletRiskController and AnalyzeWalletRisk provide a platform-wide view of wallets and risk indicators. Risk output should support prioritisation and investigation rather than automatic adverse treatment without review.
35 Phase 14 - AI-Powered Wallet Intelligence
|
STEP |
Generate Wallet AI Insights Primary user: Administrator and landlord management |
WalletAIAnalyzer produces country-level insight, transaction-pattern analysis and actionable recommendations. LandlordWalletService can predict cash flow and calculate a financial health score.
|
AI capability |
Input |
Output |
|
Country wallet insights |
Wallets and activity for a country. |
Trends, risks and opportunities. |
|
Transaction-pattern analysis |
Selected transaction set. |
Unusual or recurring patterns. |
|
Wallet recommendations |
Statistics and trends. |
Suggested actions. |
|
Cash-flow prediction |
Landlord history and future period. |
Projected inflows and outflows. |
|
Financial health score |
Landlord wallet data. |
Portfolio financial indicator. |
|
AI performance / retrain |
Model outcomes and training controls. |
Monitoring and model-management view. |
|
|
AI recommendations are advisory AI does not replace finance, fraud, compliance or treasury approval. Missing, delayed or incorrect transaction data can produce misleading results. |
Automated analytical commands
· TrackWalletGrowth - records wallet growth trends.
· GenerateWalletFinancialReports - creates scheduled wallet reports.
· CalculateWalletHealthScores - recalculates health scores in bulk.
· AnalyzeWalletRisk - runs platform-wide risk analysis.
36 Phase 15 - Platform-Wide Wallet Administration
|
STEP |
Review All Wallets and Platform Statistics Primary user: Wallet administrator |
WalletController provides all-wallet views, individual admin detail, platform summaries, statistics and data refresh actions.
|
Action |
Purpose |
|
allWalletsPage / allWalletsJson / getAllWallets |
Lists wallets across the platform. |
|
adminShow |
Opens a user’s wallet detail. |
|
getWalletSummary |
Provides platform-level balance and status summary. |
|
getDetailedWalletStatistics |
Provides deeper wallet metrics. |
|
refreshWalletData / refreshData |
Refreshes calculated or cached wallet information. |
37 Administrative Balance Adjustments and Manual Transactions
|
STEP |
Adjust, Deposit, Reconcile or Force a Transaction Primary user: Restricted administrator |
Manual administrative actions are intended for controlled correction, recovery or exceptional operations. They must never be used to conceal a gateway, payout or reconciliation problem.
|
Action |
Use |
Required evidence |
|
adjustBalance |
Manual credit or debit adjustment. |
Reason, authorisation and audit reference. |
|
deposit |
Administrative deposit. |
Source and approval. |
|
forceTransaction |
Creates a transaction outside the normal user flow. |
Incident or approved operational reason. |
|
reconcileWallet |
Compares balance with transaction history. |
Reconciliation report and adjustment decision. |
|
bulkAdjustBalance |
Applies multiple adjustments. |
Validated file, totals and multi-level approval. |
|
|
Never edit the balance without a transaction Every adjustment should create a WalletTransaction and WalletTransactionAudit entry. The previous balance, adjustment amount, new balance, reason and administrator should be traceable. |
38 Create Missing Wallets and Manual Transactions
|
STEP |
Create a Wallet for a User Without One Primary user: Wallet administrator |
Use showCreateForm, getUsersWithoutWallets and createWallet to recover or provision an eligible account that does not have a wallet.
|
☐ |
User is eligible for a wallet. |
|
☐ |
No existing wallet is hidden or duplicated. |
|
☐ |
Correct user type and currency are selected. |
|
☐ |
Opening balance is authorised. |
|
☐ |
Creation reason is recorded. |
|
☐ |
The user receives the expected access and notification. |
showCreateTransactionForm and createTransaction support a manual transaction under restricted administrative controls.
39 Regional and Country Wallet Management
|
STEP |
Review Wallet Activity by Region and Country Primary user: Super administrator / regional management |
RegionalWalletController, RegionalWalletTrendController and CountryWalletDashboard provide geographic breakdowns, trends, payouts and reports.
|
Action |
Purpose |
|
regionsIndex |
Lists regions and wallet summaries. |
|
regionsTrend |
Shows regional changes over time. |
|
regionsFilter |
Filters activity by region. |
|
regionsReport |
Generates a regional report. |
|
regionsExport |
Exports regional data. |
|
regionsShow |
Shows one region in detail. |
|
countryWallets |
Lists wallets for one country. |
|
countryPayouts |
Lists payouts for one country. |
|
allCountries |
Shows all countries with wallet activity. |
|
SendRegionWalletReport / RegionWalletReportMail |
Produces and sends automated regional reports. |
|
|
Regional reporting must preserve currency context A consolidated regional amount should state the reporting currency, rate source and conversion date. Do not sum different currencies without a defined conversion method. |
40 Real-Time Monitoring, Suspicious Flags and Wallet Audit
|
STEP |
Monitor Transactions in Real Time Primary user: Wallet operations / risk team |
WalletRealTimeMonitorController displays live or frequently refreshed transaction activity. WalletTransactionMonitorController provides suspicious views and manual flagging.
|
STEP |
Review and Export Wallet Audit Records Primary user: Auditor / administrator |
WalletAuditController provides wallet audit detail, statistics, bulk updates and export to PDF, CSV or JSON.
|
Audit item |
Example |
|
Wallet creation |
User, currency, initial status. |
|
Settings change |
PIN, limit, notification or currency change. |
|
Transaction |
Credit, debit, transfer, payment or withdrawal. |
|
Administrative adjustment |
Previous and new balance, reason and admin. |
|
Freeze / unfreeze |
Alert, investigator, reason and decision. |
|
Payout action |
Request, approval, provider result and final status. |
|
Export |
User, scope, format and timestamp. |
41 Wallet Consent and Privacy Management
|
STEP |
Manage Wallet Data Consent Primary user: Super administrator / privacy team |
WalletConsentController stores user consent records for wallet data processing where required. Consent management supports governance but does not itself determine the legal basis for every wallet activity.
|
☐ |
Purpose and scope of consent are clear. |
|
☐ |
Consent date and source are recorded. |
|
☐ |
Withdrawal process is available where applicable. |
|
☐ |
Mandatory transaction records are retained under legal and contractual requirements. |
|
☐ |
Sensitive wallet and fraud data are access-controlled. |
|
☐ |
Exports and regional reports minimise unnecessary personal information. |
42 Property Wallet, Lender Wallet and Government Wallet
|
STEP |
Use Property-Level Wallets Primary user: Landlord / property finance team |
PropertyWallet separates financial activity by property. PropertyWalletUpdated is fired when the balance changes, and PropertyWalletAnalyticsAdminController provides revenue, expense and net operating income views.
|
Property wallet use |
Value |
|
Rent collection allocation |
Shows wallet-linked income for one property. |
|
Expense tracking |
Associates wallet-funded costs with the property. |
|
NOI analysis |
Supports property-level operating performance. |
|
Fraud monitoring |
PropertyWalletFraudService can inspect property wallet patterns. |
|
Portfolio comparison |
Enables performance comparison between properties. |
|
STEP |
Use Lender Wallets Primary user: Registered lender / financing marketplace |
LenderWallet and LenderWalletTransaction support dedicated lender balances and transaction history. LenderWalletService manages lender operations and should preserve financing application and settlement context.
|
STEP |
Use the Government Agency Wallet Primary user: Government agency / authorised administrator |
GovAgencyWalletController supports a dedicated wallet receiving configured government remittances. GovPayoutStatusNotification communicates payout status to the agency.
|
|
Domain-specific controls apply Property, lender and government wallets should not inherit user-facing actions automatically. Each wallet type should expose only the operations required for its role. |
43 Events, Notifications, Mail, Jobs and Commands
|
Event |
Trigger |
|
WalletTransactionCreated |
New wallet transaction created. |
|
WalletUpdated |
Wallet balance or state updated. |
|
WalletFrozenAlert |
Wallet frozen because of a security or fraud concern. |
|
PropertyWalletUpdated |
Property wallet balance changed. |
|
PayoutRequested |
Withdrawal or payout request created. |
|
LandlordPayoutUpdated |
Landlord payout status changed. |
|
Notification |
Recipient |
Trigger |
|
WalletCreditedNotification |
User |
Wallet top-up confirmed. |
|
WalletWithdrawalNotification |
Client/Tenant |
Withdrawal initiated. |
|
PayoutProcessed |
User |
Payout completed. |
|
ManualPayoutRequired |
Administrator |
Automated payout requires manual action. |
|
GovPayoutStatusNotification |
Government agency |
Government payout status changed. |
|
TenantSepaExpiryNotification |
Client/Tenant |
SEPA mandate is expiring. |
|
Mail class |
Purpose |
|
WalletBalanceUpdated |
Balance update email. |
|
WalletInvoiceMail |
Top-up invoice. |
|
WalletWithdrawalConfirmation |
Withdrawal confirmation. |
|
WalletCurrencyChangeConfirmation |
Wallet currency change confirmation. |
|
RegionWalletReportMail |
Automated regional wallet report. |
|
Job |
Purpose |
|
ProcessLandlordPayout / ProcessLandlordPayoutJob |
Executes landlord payouts. |
|
ProcessTenantPayoutJob |
Executes client withdrawals. |
|
CalculateWalletHealthScore |
Calculates a wallet health score. |
|
SendRegionWalletReport |
Sends regional reports. |
|
Command |
Purpose |
|
CalculateWalletHealthScores |
Bulk health-score calculation. |
|
AnalyzeWalletRisk |
Platform-wide risk analysis. |
|
ProcessScheduledWalletPayments |
Processes due recurring wallet payments. |
|
TrackWalletGrowth |
Records wallet growth trends. |
|
GenerateWalletFinancialReports |
Generates wallet financial reports. |
|
|
Background processing must be observable Queues and commands should have retry, failure, alert and idempotency controls. A failed job must not create duplicate credits, debits or payouts when retried. |
44 Backend Models Reference
|
Model |
Purpose |
|
Wallet |
Core user wallet: balance, currency, status, PIN and freeze flag. |
|
PropertyWallet |
Dedicated property-level wallet. |
|
LenderWallet / LenderWalletTransaction |
Lender balance and transactions. |
|
WalletTopup |
Top-up request and provider status. |
|
WalletTransaction |
All wallet credits, debits and transfers. |
|
WalletTransactionAudit |
Transaction-level audit trail. |
|
WalletCategory / WalletTransactionCategory |
Transaction classification. |
|
WalletRiskIndicator |
Risk and health signals. |
|
WalletGrowthTrend |
Historical wallet growth. |
|
WalletInteractionGraph |
Wallet-to-wallet relationship data. |
|
WalletFinancialReport |
Generated wallet report. |
|
ScheduledWalletPayment |
Recurring payment instruction. |
|
LandlordPayout |
Landlord payout record. |
|
TenantPayout |
Client withdrawal record. |
|
PayoutAudit |
Payout audit trail. |
|
AutomatedPayoutRule |
Automatic landlord payout rule. |
|
TenantBankAccount |
Saved withdrawal account. |
|
UserVirtualAccount / DepositAccount |
Virtual account and deposit relationship. |
45 Controllers and Services Reference
|
Controller |
Main purpose |
|
WalletController |
Shared wallet actions: top-up, payment methods, transactions, admin views, adjustments and settings. |
|
LandlordWalletController |
Landlord dashboard, portfolio, transfer, withdrawal, bulk payment and analytics. |
|
EnterpriseWalletController |
Multi-property, consolidation, approval workflows, bulk payment and audit. |
|
WalletAnalyticsController (Landlord) |
Trends, interaction graph, balance and gateway performance. |
|
WalletSecurityController |
Fraud alerts, patterns, limits, IP, 2FA, audit and recommendations. |
|
TenantWalletController |
Client dashboard, withdrawal, bank accounts and SEPA timeline. |
|
Mobile\WalletController |
Mobile top-up, pay, transfer, withdraw, banks, analytics, security and receipts. |
|
WalletCategoryController |
User transaction categories. |
|
WalletFraudAdminController |
Admin fraud alerts, patterns and investigations. |
|
WalletFreezeController |
Administrative unfreeze. |
|
WalletTopupController |
Platform top-up and invoice administration. |
|
WalletAIInsightsAdminController |
AI insights, performance and retraining. |
|
WalletAuditController |
Audit detail, statistics and export. |
|
WalletCurrencyAdminController |
Rates, live updates, markup and FX revenue. |
|
WalletRealTimeMonitorController |
Live transaction view. |
|
WalletTransactionMonitorController |
Suspicious transactions and flagging. |
|
WalletRiskController |
Platform-wide wallet risk. |
|
WalletSettingsController |
Platform wallet configuration. |
|
WalletReportController |
Administrative wallet reporting. |
|
WalletGraphController |
Wallet interaction graph. |
|
RegionalWalletController / TrendController |
Country and regional wallet management. |
|
WalletCategoryAdminController |
Platform category management. |
|
WalletConsentController |
Wallet-data consent records. |
|
WalletSepaController |
SEPA wallet management. |
|
PropertyWalletAnalyticsAdminController |
Property wallet analytics. |
|
GovAgencyWalletController |
Government agency wallet. |
|
Service |
Purpose |
|
LandlordWalletService |
Landlord wallet creation, statistics, portfolio, health score and cash-flow prediction. |
|
LenderWalletService |
Lender wallet operations. |
|
PropertyDevelopmentWalletService |
Property-development wallet operations. |
|
PropertyWalletFraudService |
Property wallet fraud detection. |
|
WalletAIAnalyzer |
Country insight, transaction patterns and recommendations. |
|
WalletTopUpNotificationService |
Top-up notifications. |
|
WalletWithdrawalNotificationService |
Withdrawal notifications. |
|
EmbedlyVirtualAccountService |
Embedly virtual-account provisioning. |
|
FlutterwaveVirtualAccountService |
Flutterwave virtual-account provisioning. |
|
CurrencyService / conversion trait |
Wallet and service currency conversion. |
|
FeeCalculationService |
Calculates platform service fees. |
|
Payment gateway services |
Top-up and payout provider integration. |
46 Status and Lifecycle Matrix
|
Record |
Status |
Meaning |
|
Wallet |
Active |
Transactions allowed subject to limits and security. |
|
Wallet |
Frozen |
Transactions blocked by EnsureWalletNotFrozen. |
|
Wallet |
Suspended |
Account restricted under platform policy. |
|
Top-up |
Pending |
Initiated but not verified. |
|
Top-up |
Completed |
Verified and wallet credited. |
|
Top-up |
Failed / cancelled |
No wallet credit. |
|
Wallet transaction |
Pending |
Created but not final. |
|
Wallet transaction |
Completed |
Final wallet movement recorded. |
|
Wallet transaction |
Failed / reversed |
Failed or corrected under controlled process. |
|
Payout |
Pending |
Requested and waiting for processing or approval. |
|
Payout |
Processing |
Provider or job handling the payout. |
|
Payout |
Completed |
Destination transfer confirmed. |
|
Payout |
Failed / rejected / cancelled |
Not completed; balance treatment required. |
|
Scheduled payment |
Active |
Will be processed at the next due time. |
|
Scheduled payment |
Paused / cancelled |
No further processing. |
|
Fraud alert |
Open / investigating |
Requires review. |
|
Fraud alert |
Resolved / false positive |
Decision recorded. |
|
|
Confirm production enums The exact enum names, automatic transitions and reversal behaviour were not fully defined in the supplied scenario. Confirm them before training users or integrating external systems. |
47 Worked Example - Multi-Property Rent Collection and Payout
|
|
Scenario Cedar Homes manages 12 rental properties. A client, Emma Clarke, has a GBP wallet and pays £1,250 monthly rent for Flat 8. Cedar Homes uses a multi-level enterprise approval for bulk vendor payments and an automated payout rule for rental income. |
|
Stage |
What happens |
|
1. Wallet creation |
Emma and Cedar Homes receive wallets automatically. Each property also has a PropertyWallet. |
|
2. Funding |
Emma tops up £1,300 using a saved tokenised card and completes 3DS. |
|
3. Verification |
The provider verifies the charge and the wallet receives the confirmed credit. |
|
4. Notification |
Emma receives WalletCreditedNotification, balance update and invoice. |
|
5. Rent payment |
Emma selects Pay with Wallet for the £1,250 rent obligation. |
|
6. Fee and debit |
The system displays the fee, confirms PIN and deducts the authorised amount. |
|
7. Lease update |
The Lease Management payment schedule is marked paid and a receipt is generated. |
|
8. Landlord payout |
LandlordPayout is created and ProcessLandlordPayout executes the configured destination. |
|
9. Property allocation |
The property wallet and property performance view reflect the collection. |
|
10. Enterprise payment |
Cedar Homes uploads a bulk maintenance payment file. |
|
11. Approval |
The property manager and finance director approve the batch. |
|
12. Processing |
The batch executes and failed rows are reviewed separately. |
|
13. Monitoring |
Wallet analytics show balance, gateway performance and category trends. |
|
14. Security |
A high-value transfer triggers extra verification and is recorded in audit. |
|
15. Reporting |
Finance exports the wallet statement, payout report and enterprise audit for month-end reconciliation. |
48 Recommended Daily, Weekly and Monthly Operating Procedures
|
Frequency |
Recommended activity |
|
Daily - operations |
Review failed top-ups, pending withdrawals, failed payouts, suspicious transactions and manual-intervention alerts. |
|
Daily - finance |
Reconcile provider receipts, wallet credits, service payments and payout references. |
|
Daily - enterprise approvers |
Review pending approval requests and expiring batches. |
|
Weekly - landlord |
Review rental income, property performance, expenses, needs-attention items and fraud alerts. |
|
Weekly - risk |
Review open investigations, frozen wallets and false positives. |
|
Weekly - admin |
Review job failures, scheduled payments, virtual-account webhooks and gateway performance. |
|
Monthly - finance |
Reconcile wallet balances, property wallets, bank settlement, payouts, fees and FX revenue. |
|
Monthly - management |
Review cash-flow prediction, wallet health, bulk payment statistics and regional trends. |
|
Quarterly - governance |
Review roles, limits, automated payout rules, approval workflows, consent, audit and model performance. |
49 Implementation and Onboarding Checklist
Business rules
|
☐ |
Eligible user types for automatic wallet creation. |
|
☐ |
Country-to-currency mapping. |
|
☐ |
Wallet status and freeze rules. |
|
☐ |
Transaction PIN and retry policy. |
|
☐ |
Top-up and payment limits. |
|
☐ |
Withdrawal and payout limits. |
|
☐ |
Fee and FX markup rules. |
|
☐ |
Scheduled payment rules. |
|
☐ |
Automated payout rules. |
|
☐ |
Enterprise approval thresholds. |
Provider configuration
|
☐ |
Enabled payment gateways by country. |
|
☐ |
Saved card tokenisation support. |
|
☐ |
SEPA mandate and settlement policy. |
|
☐ |
Virtual account provider and webhook verification. |
|
☐ |
Bank account verification provider. |
|
☐ |
Landlord and client payout providers. |
|
☐ |
Provider credentials, callback URLs and webhooks. |
|
☐ |
Retry and timeout handling. |
Governance and security
|
☐ |
Wallet admin and enterprise roles. |
|
☐ |
Fraud investigation and freeze authority. |
|
☐ |
Adjustment and force-transaction approval. |
|
☐ |
Payout exception handling. |
|
☐ |
Audit retention and export access. |
|
☐ |
Consent and privacy handling. |
|
☐ |
High-value verification thresholds. |
|
☐ |
Incident and recovery procedure. |
50 User Acceptance Testing and Go-Live Checklist
|
Test area |
Acceptance test |
|
Wallet creation |
Register each user type and confirm wallet, currency and status. |
|
Settings |
Change PIN, notifications, limits and currency preference. |
|
Gateway top-up |
Test success, failure, cancellation and duplicate callback. |
|
Saved card |
Tokenise, charge, complete 3DS and remove method. |
|
SEPA |
Create mandate, timeline, collection and expiry alert. |
|
Virtual account |
Create account and test automatic credit. |
|
Rent payment |
Pay a lease obligation and verify landlord payout. |
|
Service payment |
Pay a property purchase, land or WeBuild obligation. |
|
Scheduled payment |
Process a successful and insufficient-funds run. |
|
Transfer |
Test same-currency and cross-currency transfer. |
|
Client withdrawal |
Verify bank, create payout and test success/failure. |
|
Landlord payout |
Test manual and automated payout rules. |
|
Bulk payment |
Validate, approve, process and reconcile batch. |
|
Enterprise approval |
Test each level, rejection, expiry and audit. |
|
Multi-currency |
Test rates, markup, conversion and currency history. |
|
Fraud |
Create an alert, investigate, freeze and unfreeze. |
|
Health score |
Run individual and bulk score calculations. |
|
Admin adjustment |
Create authorised credit and debit adjustments. |
|
Regional report |
Generate, export and send a regional report. |
|
Audit |
Verify every sensitive action is recorded. |
|
API / jobs |
Test retries, idempotency and failed-job alerts. |
|
Exports |
Open CSV, Excel, PDF and JSON outputs and verify totals. |
|
|
Pilot before full financial rollout Use test accounts and a limited pilot with small approved amounts. Confirm transaction integrity, provider settlement, reversal, audit and support processes before enabling all users and properties. |
51 Common Issues and Troubleshooting
|
Issue |
Recommended action |
|
Wallet was not created |
Check registration listener, user eligibility, LandlordWalletService and duplicate constraints. |
|
Wrong default currency |
Review country mapping and user country data. |
|
Top-up shows paid but balance is unchanged |
Review provider verification, WalletTopup status, WalletTransaction creation and observer logs. |
|
Wallet credited twice |
Check webhook idempotency and unique provider reference. |
|
Saved card cannot be charged |
Check token status, gateway, 3DS and country availability. |
|
Virtual-account transfer missing |
Review provider webhook, reference, account mapping and duplicate protection. |
|
Rent payment debited but lease is unpaid |
Review cross-module callback, transaction and lease payment update. |
|
Transfer debited sender only |
Stop further processing and apply atomic rollback or approved reconciliation. |
|
Withdrawal remains pending |
Check payout job, bank verification, provider response and manual intervention alert. |
|
Payout failed after client payment |
Preserve the client’s confirmed payment and resolve landlord payout separately under policy. |
|
Scheduled payment did not run |
Review due time, command schedule, wallet status, balance and linked service. |
|
Wallet is frozen unexpectedly |
Review fraud alert, risk indicator, admin action and audit log. |
|
Currency conversion is wrong |
Check rate source, timestamp, markup, rounding and original currency. |
|
Bulk payment total differs |
Review invalid rows, duplicates, fees, currency and partial completion. |
|
Admin adjustment changed balance without history |
Create an incident and reconcile through a controlled transaction and audit record. |
|
Dashboard totals differ from transactions |
Review filters, pending statuses, currency consolidation and cached data. |
|
Health score seems inaccurate |
Review source factors, data freshness and scoring job. |
|
Regional report totals look inflated |
Check cross-currency conversion and duplicate consolidation. |
|
Receipt cannot be downloaded |
Verify transaction ownership, status and document generation. |
|
Audit export is incomplete |
Review date range, permissions, filters and archived records. |
52 Frequently Asked Questions
Does every user automatically receive a wallet?
The supplied design creates a wallet at registration and includes get-or-create support for landlords.
Can a property have its own wallet?
Yes. PropertyWallet supports property-level financial tracking.
How can users add money?
Through supported gateways, saved tokenised cards, SEPA direct debit, virtual accounts or an authorised administrative deposit.
Can wallet funds pay rent and property transactions?
Yes. The supplied flow covers rent, leases and supported services such as property purchase, WeBuild and land instalments.
Can a user transfer to another wallet currency?
The supplied flow includes currency conversion for different wallet currencies.
Can tenants withdraw to a bank account?
Yes, after bank-account verification and TenantPayout creation.
Can landlords automate withdrawals?
AutomatedPayoutRule supports configured payout conditions.
Can a company require transaction approvals?
EnterpriseWalletController supports multi-level approval workflows.
Can the company process many payments at once?
Yes. Landlord and enterprise bulk payment flows support CSV/Excel upload and processing.
What happens when a wallet is frozen?
EnsureWalletNotFrozen blocks transactions; exact handling of incoming credits should be confirmed.
Does AI decide fraud automatically?
AI and fraud services flag risk. Investigation and freeze/unfreeze decisions require authorised review.
Can wallet activity be exported?
Transactions, statements, analytics, regional data and audits have multiple export options.
Can users change wallet currency?
The supplied implementation includes switchWalletCurrency and currency history; balance treatment requires production confirmation.
Are top-ups and payouts instant?
The system can process immediately, but actual timing depends on provider verification, banking and compliance conditions.
Does a successful wallet payment mean the landlord has received bank settlement?
The client payment and landlord payout are related but separate statuses. Payout settlement must be monitored and reconciled.
53 Technical Matters to Confirm Before Production Sign-Off
|
Area |
Confirmation required |
|
Wallet uniqueness |
Confirm one wallet per user/currency or another supported model. |
|
Opening balance |
Confirm new-wallet balance and migration treatment. |
|
Status enums |
Confirm Active, Frozen, Suspended and all transaction/top-up/payout statuses. |
|
PIN policy |
Confirm length, encryption, retry, lockout and reset. |
|
Balance availability |
Confirm available, pending and reserved balance behaviour. |
|
Top-up credit timing |
Confirm provider verification, settlement and chargeback treatment. |
|
Saved card compliance |
Confirm token storage and provider responsibilities. |
|
SEPA |
Confirm mandate provider, settlement, return and expiry rules. |
|
Virtual account |
Confirm supported countries, account lifecycle and webhook idempotency. |
|
Transfer atomicity |
Confirm database transaction, FX locking and reversal. |
|
Fee treatment |
Confirm fee payer, ledger entries, refunds and taxes. |
|
Payout processing |
Confirm job names, queue, retries, provider mapping and duplicate prevention. |
|
Automated payout |
Confirm thresholds, retained balance, frequency and cancellation. |
|
Approval workflows |
Confirm rule priority, threshold currency and delegation. |
|
Bulk payments |
Confirm template, size limits, validation, partial success and rollback. |
|
Currency switching |
Confirm whether balances convert or new currency wallets are created. |
|
Exchange rates |
Confirm source, frequency, markup, rounding and fallback. |
|
Fraud engine |
Confirm alert rules, auto-freeze threshold and investigation evidence. |
|
Health score |
Confirm factors, explanation and permitted business use. |
|
AI model management |
Confirm data, performance measures, retrain authority and rollback. |
|
Admin adjustments |
Confirm dual approval, required reason and immutable audit. |
|
Regional consolidation |
Confirm reporting currency and inter-region data rules. |
|
Government wallet |
Confirm permitted remittance flows and access scope. |
|
Consent and privacy |
Confirm retention, DSAR, access and data residency. |
|
API and webhooks |
Confirm authentication, scopes, rate limits, signatures and error contracts. |
|
|
Do not treat unconfirmed behaviour as production policy This guide is based on the detailed scenario supplied for Leaseora. Items not explicitly defined are listed here for technical and operational confirmation. |
54 Quick Reference - Complete Wallet Operating Flow
1. User registers and receives the appropriate wallet.
2. Confirm wallet owner, default currency, Active status and zero or approved opening balance.
3. Configure PIN, notifications, spending limits and auto-collection preferences.
4. Add and verify saved payment methods.
5. Add and verify bank accounts for withdrawal.
6. Create a virtual account where available.
7. Initiate a top-up by gateway, saved card, SEPA or virtual account.
8. Verify the external funding result before wallet credit.
9. Create the WalletTransaction and update the balance.
10. Send wallet credit, balance and invoice notifications.
11. Pay rent, lease or a supported Leaseora service from wallet balance.
12. Calculate FX and fees before confirmation.
13. Create the linked service payment and landlord payout.
14. Schedule recurring wallet payments where permitted.
15. Transfer funds to another wallet using one atomic reference.
16. Create a client withdrawal to a verified bank account.
17. Create or process a landlord payout or automated payout rule.
18. Review payout status, exceptions and audit.
19. Use landlord dashboards for portfolio, property and income performance.
20. Upload and validate bulk payment files.
21. Apply enterprise approval workflows before processing.
22. Review enterprise consolidation and audit exports.
23. Review client balance, scheduled payments and wallet health.
24. Use transaction history, receipts, statements and exports.
25. Categorise transactions for wallet analytics.
26. Review rates, markup and currency history for multi-currency activity.
27. Monitor transaction limits, PIN, 2FA and high-value verification.
28. Investigate fraud alerts and freeze wallets when authorised.
29. Run wallet health and platform risk analysis.
30. Generate AI insights, cash-flow predictions and wallet reports.
31. Review all wallets, regional activity and real-time transaction feeds.
32. Use controlled admin adjustments only with complete audit evidence.
33. Manage wallet consent and sensitive data access.
34. Reconcile wallet balances, providers, bank settlement and payouts regularly.
35. Export authorised transaction, payout, audit and regional reports.
|
|
Business value Leaseora Wallet gives a real estate company one connected financial layer for client funding, rent and service payments, property-level income, landlord payouts, enterprise approvals, multi-currency operations, fraud controls, analytics and audit. |
LEASEORA
WALLET MODULE
Fund, collect, pay, transfer, withdraw and control real estate money flows from one connected platform.
|
|
Support and onboarding For wallet configuration, provider setup, enterprise approvals, transaction testing, staff training or operational assistance, contact Leaseora through support@leaseora.com. |
leaseora.com
Tags
Was this article helpful?
Your feedback helps us improve our documentation.