PAYMENT GATEWAY MANAGEMENT
The Payment Gateway module is Leaseora's central payment-orchestration layer. It determines which gateway is available, configured and suitable for a transaction; initiates the payment; verifies the provider result; records operational outcomes; triggers downstream payout or business actions; monitors provider health; and applies failover controls when a gateway becomes unreliable.
|
LEASEORA PAYMENT GATEWAY MANAGEMENT Detailed User and Technical Operations Guide Configuration • Credentials • Country Availability • Routing • Health • Failover • Verification • Recurring Payments • Refunds • Analytics • APIs |
For real estate companies, platform administrators, finance teams, technical teams, property managers, lenders and government-payment users
Version 1.0 | July 2026
|
|
Purpose of this guide This guide explains how Leaseora's Payment Gateway module is configured, operated, monitored and supported from platform level through landlord, property and client payment flows. It also provides detailed technical reference for gateway implementations, routing, callbacks, health monitoring, circuit-breaker failover, analytics, APIs, specialist gateway domains and operational controls. |
1 Purpose, Audience and Scope
The Payment Gateway module is Leaseora's central payment-orchestration layer. It determines which gateway is available, configured and suitable for a transaction; initiates the payment; verifies the provider result; records operational outcomes; triggers downstream payout or business actions; monitors provider health; and applies failover controls when a gateway becomes unreliable.
|
Item |
Description |
|
Primary users |
SuperAdmins, real estate companies, finance administrators, technical teams, property managers, lenders, government agency users and authorised support staff. |
|
Supported use cases |
Rent, lease payments, property purchases, We Build For You instalments, land payments, wallet top-ups, utilities, subscriptions, service payments, payouts, refunds and government remittances. |
|
Core scope |
Gateway registration, encrypted credentials, landlord access, property assignment, factory resolution, routing, health, failover, analytics, APIs, recurring payments, split payments and refunds. |
|
Operational boundary |
Leaseora orchestrates gateway use. Payment-provider settlement, scheme rules, acquiring, banking availability and regulatory approval remain dependent on the external provider and jurisdiction. |
|
Terminology |
Client is used in user-facing guidance. Technical references retain tenant where that is part of the supplied implementation. |
|
|
Source basis This document is based on the detailed Payment Gateway scenario supplied for Leaseora. Provider capability statements and feature-matrix values should be validated against each live provider account, country and contract before production use. |
What the module connects
· Platform governance - which gateways exist and where they may be used.
· Landlord configuration - credentials, active status, default gateway and property assignment.
· Routing - country, currency, amount, use case, health and failover priority.
· Provider integration - gateway-specific payment initiation, verification and payout methods.
· Business modules - rent, sales, We Build For You, land, wallet and utilities.
· Reliability - health checks, circuit breaker, retries, failover and incident evidence.
· Management insight - volume, success rate, cost, response time, errors and recommendations.
2 Document Map
|
Part |
Coverage |
|
Sections 1-4 |
Purpose, architecture, roles and terminology. |
|
Sections 5-8 |
SuperAdmin platform configuration and landlord access. |
|
Sections 9-12 |
Landlord setup, testing, analytics and property assignment. |
|
Sections 13-19 |
Interfaces, implementations, factory, routing and platform services. |
|
Sections 20-23 |
Health monitoring, failover, client selection and payment processing. |
|
Sections 24-28 |
Lease payments, utilities, lender, government and API access. |
|
Sections 29-33 |
Gateway matrix, security, webhooks, reconciliation and operations. |
|
Sections 34-39 |
Analytics, incidents, testing, deployment and production sign-off. |
|
Sections 40-45 |
Backend references, worked example, UAT, troubleshooting, FAQs and quick flow. |
Figure 1. Complete Payment Gateway lifecycle
3 Roles and Responsibilities
|
Role |
Primary responsibility |
Control |
|
SuperAdmin Gateway Administrator |
Registers gateways, protects platform credentials, configures scope, countries, features, fees, advanced settings and landlord availability. |
Cannot rely on hidden defaults; changes require audit and rollback. |
|
Landlord Finance Administrator |
Configures landlord credentials, default gateway, active status, property gateway options and analytics. |
Should not expose credentials or use untested production settings. |
|
Technical / Integration Team |
Implements callbacks, webhooks, routing metadata, logs, health checks, retries and testing. |
Must use server-side verification and idempotency. |
|
Property Manager |
Selects allowed gateways for individual properties and supports clients. |
Cannot mark payments successful without verified evidence. |
|
Finance / Reconciliation Team |
Confirms payment records, settlements, fees, refunds, payouts and exceptions. |
Must reconcile provider, Leaseora and bank records. |
|
Risk / Support Team |
Reviews failed or uncertain payments, complaints and gateway incidents. |
Must avoid duplicate charging while investigating. |
|
Lender / Government User |
Configures dedicated gateway flows for approved domain use. |
Access must remain separate from landlord credentials. |
|
|
Segregation of duties Separate credential management, transaction approval, payment verification, refund approval, reconciliation and incident closure where staffing allows. |
4 Core Concepts and Terminology
|
Term |
Meaning |
|
Platform gateway |
PaymentGateway record configured by SuperAdmin and available under platform rules. |
|
Landlord gateway |
LandlordGateway record containing landlord-specific credentials and status. |
|
User gateway access |
UserPaymentGateway relationship enabling a gateway for a landlord. |
|
Property gateway |
PropertyPaymentGateway relationship controlling gateway display for one property. |
|
Gateway scope |
Platform, landlord or both. |
|
Environment |
Sandbox or production. |
|
Payment initiation |
Creation of a provider session, link, intent, mandate or direct-debit instruction. |
|
Payment verification |
Server-side check of status, reference, amount, currency and metadata with the provider. |
|
Health state |
Healthy, degraded, down or unknown according to configured thresholds. |
|
Circuit breaker |
Control that stops routing to a gateway after repeated failures. |
|
Failover |
Selection of an alternative healthy gateway after a failure. |
|
Settlement |
Provider or bank transfer of collected funds; not identical to payment authorisation. |
|
Payout |
Transfer of funds to landlord, lender, client or government account. |
5 Phase 1 - Platform-Level Gateway Registration
|
STEP |
Register a Platform Gateway Primary user: SuperAdmin Gateway Administrator |
Navigate to Payment Gateways -> Platform Configuration -> Create. Add one PaymentGateway record for each provider and gateway type used by Leaseora.
|
Field |
Purpose |
|
gateway_name |
Unique identifier such as flutterwave, stripe, revolut, paystack, squad, embedly, paypal, sepa, solaris or leaseora. |
|
api_key / secret_key |
Platform credentials encrypted at rest. |
|
environment |
Sandbox or production as resolved by the effective-environment logic. |
|
scope |
Platform, landlord or both. |
|
supported_countries |
ISO country-code list used by country filters. |
|
supports_direct_debit |
Marks direct-debit capability. |
|
supports_recurring |
Marks recurring or subscription capability. |
|
supports_withdrawal |
Marks payout or withdrawal capability. |
|
fee_percentage / fee_flat |
Configured fee inputs used by calculateFee. |
|
is_active |
Global availability toggle. |
Credential handling
· Use setApiKeyAttribute and setSecretKeyAttribute so credentials are encrypted before storage.
· Use decrypted accessors only inside authorised server-side services.
· Never place secret credentials in client responses, logs, screenshots or exported reports.
· Use separate sandbox and production credentials.
· Rotate credentials under an approved change process.
Model scopes used for availability
|
Scope |
Use |
|
scopeActive |
Only globally active gateways. |
|
scopeForRegion |
Gateways available for a region. |
|
scopeSupportsDirectDebit |
Direct-debit gateways. |
|
scopeSupportsRecurring |
Recurring-payment gateways. |
|
scopeSupportsWithdrawal |
Withdrawal or payout gateways. |
|
scopeAvailableInCountry |
Gateways available for an ISO country code. |
|
scopeForPlatform |
Platform-only gateways. |
|
scopeForLandlord |
Landlord-configurable gateways. |
|
scopeForBoth |
Gateways available at both levels. |
|
|
Activation changes routing Activating or deactivating a gateway can change what users see and how payments are routed. PaymentGatewayStatusChanged should be treated as an operationally significant event. |
6 Advanced Platform Configuration
|
STEP |
Configure Advanced Gateway Settings Primary user: SuperAdmin Gateway Administrator |
Use advancedConfiguration to manage settings that differ by provider or operational risk profile.
|
Setting |
Purpose |
|
Webhook URLs |
Provider callback endpoints for server-to-server events. |
|
Retry policy |
Number, timing and conditions for retry. |
|
Timeout threshold |
Maximum wait before the call is treated as failed or uncertain. |
|
Health thresholds |
Limits for latency, success rate, errors and outage state. |
|
Failover priority |
Order of alternative gateways. |
|
Environment overrides |
Sandbox or production behaviour where supported. |
|
Country availability |
Countries where the provider is approved and configured. |
|
Feature flags |
Recurring, direct debit, withdrawal, tokenisation or specialist flow. |
SuperAdmin operational actions
· Fetch gateways for a selected country.
· Review real-time system health and aggregated health summary.
· Review platform-wide analytics and AI recommendations.
· Perform controlled bulk enable, disable or update operations.
· Test gateway connectivity using the configured environment.
|
|
Bulk changes require change control Before a bulk disable or country update, review active transactions, recurring mandates, property assignments and failover capacity. |
7 Gateway Scope and Availability Model
Figure 2. Platform, landlord and client gateway scope
|
Scope |
Configuration owner |
Typical use |
|
platform |
SuperAdmin credentials and platform use cases. |
Wallet top-up, subscription, platform service or configured platform transaction. |
|
landlord |
Landlord supplies and controls their own credentials. |
Landlord property or client payments. |
|
both |
Can operate through platform or landlord context. |
Use is selected by the configured service and business rule. |
|
|
Scope does not grant automatic access A gateway can support landlord scope but still require SuperAdmin enablement, valid landlord credentials, active status, property assignment and country eligibility. |
8 Landlord Gateway Access Management
|
STEP |
Enable or Disable Gateways for Landlords Primary user: SuperAdmin Gateway Administrator |
Open landlordGatewayManagement to control which landlords may configure and use each gateway.
1. Search or select the landlord.
2. Review the landlord's country, business model and payment use cases.
3. Select an eligible gateway.
4. Enable the gateway through enableGatewayForLandlord.
5. Record the administrator and operational notes.
6. Confirm that UserPaymentGateway was created.
7. Test the landlord-status view.
8. Use bulk enablement only for a verified landlord group.
Disablement process
1. Confirm the reason and effective time.
2. Review active payments, recurring mandates and pending callbacks.
3. Disable the gateway for the landlord.
4. Record the administrator and reason.
5. Confirm remaining healthy alternatives.
6. Notify the landlord where operationally required.
|
|
Disabling access can affect active clients Do not disable a gateway without reviewing unpaid invoices, recurring payments, pending verification and the property's remaining options. |
9 Phase 2 - Landlord Gateway Dashboard
|
STEP |
View and Configure Landlord Gateways Primary user: Landlord Finance Administrator |
Navigate to Payment Gateways. The dashboard should show gateways enabled by SuperAdmin and filtered by landlord configuration.
|
Dashboard area |
Meaning |
|
Gateway availability |
Enabled gateways that the landlord may configure. |
|
Active / default status |
Whether the gateway can be used and whether it is preferred. |
|
Health status |
Uptime, response time, success rate and current state. |
|
Performance |
Volume, value, revenue, errors and response time. |
|
Cost |
Configured percentage and flat fees or calculated cost analysis. |
|
Recommendations |
Suggested configuration or use-case changes based on data. |
Landlord configuration process
1. Select a gateway enabled for the landlord.
2. Enter landlord-specific credentials when required.
3. Save the LandlordGateway record.
4. Test the connection.
5. Activate the gateway after a successful test.
6. Set a default only after comparing country, use case, health and cost.
7. Assign the gateway to properties where needed.
|
|
Default is a preference, not a guarantee Routing may use another gateway when the default is unavailable, unsuitable for the client country or use case, unhealthy or superseded by failover rules. |
10 Landlord Credentials and Configuration Validation
LandlordGateway stores landlord_id, payment_gateway_id, credentials, active status, default status and transaction success or failure counters.
|
Control |
How it is used |
|
isConfiguredForLandlord |
Checks required configuration and credentials. |
|
markSuccess |
Records a successful transaction and supports circuit-breaker recovery. |
|
markFailure |
Records a failed transaction and supports failover. |
|
is_active |
Controls whether the landlord gateway can be selected. |
|
is_default |
Marks the preferred landlord gateway. |
Credential checklist
|
☐ |
Credentials belong to the correct legal entity and environment. |
|
☐ |
The provider account is active and allowed to process the expected currencies. |
|
☐ |
Callback and webhook URLs are registered with the provider. |
|
☐ |
Required permissions are enabled for collection, refund or payout. |
|
☐ |
Keys have not expired or been revoked. |
|
☐ |
No secret appears in logs, screenshots or exported files. |
11 Connection Testing
|
STEP |
Test a Landlord Gateway Connection Primary user: Landlord Finance Administrator / technical team |
Use testConnection to instantiate the configured gateway through PaymentGatewayFactory and send a minimal provider call.
|
Test output |
Interpretation |
|
Connection status |
Whether the provider API can be reached. |
|
Response time |
Latency of the test request. |
|
Credential validity |
Whether the provider accepts the configured credentials. |
|
Environment |
Whether the call used sandbox or production. |
|
Error details |
Configuration, network, authentication or provider error. |
After a failed test
1. Confirm environment and base URL.
2. Confirm API key, secret and account status.
3. Confirm IP, domain or webhook allow-list requirements.
4. Check provider outage or maintenance.
5. Review exact response code without exposing the secret.
6. Correct the configuration and retest.
7. Do not activate the gateway until the test passes or a documented limitation is accepted.
12 Gateway Analytics and Recommendations
|
STEP |
Review Landlord Gateway Analytics Primary user: Landlord Finance Administrator / management |
|
Analysis |
Purpose |
|
Transaction summary |
Total attempts, verified transactions, value and revenue. |
|
Performance metrics |
Success rate, latency and error rate per gateway. |
|
Monthly trends |
Volume and performance over time. |
|
Cost analysis |
Gateway fees and cost by provider and currency. |
|
Error analysis |
Breakdown by gateway and error type. |
|
Gateway comparison |
Side-by-side performance for a selected number of days. |
|
Performance trends |
Improvement or deterioration over time. |
|
Recommendations |
Suggested gateway or use-case optimisation. |
Recommended management questions
· Which gateway has the best verified success rate for each country and currency?
· Which gateway has the lowest total cost after fees and failure impact?
· Where are response times causing client drop-off?
· Which errors are configuration issues rather than provider issues?
· Is the default gateway still the best operational choice?
· Are fallback gateways sufficiently healthy and tested?
|
|
Use comparable definitions Compare the same period, currency, payment type and verification status. Do not compare authorised payments from one provider with settled payments from another. |
13 Property-Level Gateway Assignment
|
STEP |
Assign Gateways to Properties Primary user: Landlord Finance Administrator / property manager |
Use PropertyPaymentController@configureGateway to link each property to one or more PaymentGateway records through PropertyPaymentGateway.
1. Open the property payment configuration.
2. Review property country, currency and payment types.
3. Select gateways that are enabled and configured for the landlord.
4. Confirm current health and provider support.
5. Save the property-gateway relationships.
6. Test the client payment page.
7. Confirm that unsupported gateways are not displayed.
|
|
Property assignment narrows client choice A gateway may be available to the landlord but hidden for a property until PropertyPaymentGateway permits it. |
14 Phase 3 - Gateway Interface and Abstract Layer
|
STEP |
Understand the Gateway Contract Primary user: Technical team |
Every gateway implementation follows Services\Payment\GatewayInterface.php so business modules can use a consistent contract.
|
Method |
Purpose |
|
processPayment(array $data): array |
Initiates a payment and returns provider or session data. |
|
sendToBankAccount(array $data): array |
Initiates a payout or bank transfer when supported. |
|
getName(): string |
Returns the gateway identifier. |
|
isAvailableForCountry(string $country): bool |
Checks country availability. |
AbstractGateway provides shared default logic. Provider-specific classes override or extend behaviour for authentication, payloads, verification, refunds, tokenisation, direct debit or payout.
|
|
Do not bypass the interface without need Business modules should use the factory and service layer rather than creating provider classes directly. This preserves routing, testing, health, failover and common logging. |
15 Concrete Gateway Implementations
|
Class |
Gateway |
Specified region / use case |
|
FlutterwaveGateway |
Flutterwave |
Africa including configured Nigeria, Ghana and Kenya use cases. |
|
StripeGateway |
Stripe |
Configured global use cases including US, UK and EU. |
|
RevolutGateway |
Revolut |
UK and EU. |
|
RevolutBusinessGateway |
Revolut Business |
UK and EU business-account use cases. |
|
PayStackGateway |
Paystack |
Nigeria and Ghana. |
|
SquadGateway |
Squad |
Nigeria. |
|
PayPalGateway |
PayPal |
Configured global use cases. |
|
SepaGateway |
SEPA |
EU direct-debit use cases. |
|
SolarisGateway |
Solaris |
Germany and EU. |
|
EmbedlyGateway |
Embedly |
Wallet and virtual-account use cases in configured regions. |
|
LeaseoraGateway |
Leaseora Native |
Internal platform payment flows. |
Each implementation is expected to provide processPayment, verifyPayment and verifyTransaction according to the supplied design. Provider-specific refund, tokenisation, direct-debit and payout methods may be added where required.
|
|
Validate the live provider contract The implementation table reflects the supplied Leaseora design. Actual countries, currencies, recurring features, payouts and tokenisation depend on the provider account, product and jurisdiction. |
16 Gateway Feature Matrix
|
Gateway |
Region |
Recurring |
Direct debit |
Withdrawal |
Tokenisation |
|
Flutterwave |
Africa |
Yes |
No |
Yes |
Yes |
|
Stripe |
Global |
Yes |
No |
Yes |
Yes |
|
Revolut |
UK / EU |
Yes |
No |
Yes |
Yes |
|
Revolut Business |
UK / EU |
Yes |
No |
Yes |
Yes |
|
Paystack |
Nigeria / Ghana |
Yes |
No |
Yes |
Yes |
|
Squad |
Nigeria |
Yes |
No |
Yes |
Yes |
|
PayPal |
Global |
Yes |
No |
Yes |
Yes |
|
SEPA |
EU |
Yes |
Yes |
No |
No |
|
Solaris |
Germany / EU |
Yes |
Yes |
Yes |
Yes |
|
Embedly |
Multi-region |
Yes |
No |
Yes |
Yes |
|
Leaseora Native |
Internal |
Yes |
No |
Yes |
No |
|
|
Feature-matrix caution This matrix is reproduced from the supplied module specification. Confirm actual provider and account capability before displaying a feature or routing a live payment. |
17 Payment Gateway Factory
|
STEP |
Resolve the Correct Gateway Class Primary user: Technical team |
PaymentGatewayFactory is the central class resolver. It accepts a PaymentGateway model and returns the correct gateway implementation.
1. Receive the selected PaymentGateway model.
2. Normalise the gateway name.
3. Map the name to the concrete implementation.
4. Inject the appropriate configuration and credentials.
5. Return the implementation through the common interface.
6. Raise a controlled error for unsupported or misconfigured names.
|
|
Factory mapping is production-critical A naming mismatch can route a payment to the wrong implementation or fail at runtime. Include every supported gateway in automated tests. |
18 Gateway Router and Native Routing
|
STEP |
Route a Payment to the Optimal Gateway Primary user: GatewayRouterService |
GatewayRouterService@processPayment uses the landlord, client, amount and metadata to select and initiate the payment.
|
Routing factor |
Control |
|
Landlord configuration |
Only enabled, active and configured landlord gateways. |
|
Client country |
Only gateways available in the client's country. |
|
Amount and currency |
Gateways able to process the transaction context. |
|
Use case |
Rent, sale, We Build For You, land, wallet, utility, subscription or payout. |
|
Gateway health |
Healthy or approved degraded gateways. |
|
Failover rules |
Priority order and circuit-breaker state. |
|
Property assignment |
Only gateways allowed for the relevant property. |
LeaseoraGatewayRouter provides the internal routing layer for Leaseora-native transactions.
Figure 3. Routing, verification and failover
19 Phase 4 - Platform Gateway Services
|
STEP |
Use PlatformPaymentGatewayService Primary user: Platform payment services |
|
Method |
Purpose |
|
getAvailableGateways |
Returns gateways for a use case and user. |
|
getWalletFundingGateways |
Returns wallet top-up options. |
|
getSubscriptionGateways |
Returns recurring or subscription options. |
|
getPayoutGateways |
Returns withdrawal or payout options. |
|
getServicePaymentGateways |
Returns service-payment options. |
|
getBestGatewayForUser |
Selects one optimal option. |
|
getAllEnabledPlatformGateways |
Returns all platform-enabled gateways. |
|
validatePlatformGatewayCredentials |
Checks platform configuration. |
|
isPlatformGatewayEnabled |
Checks global gateway status. |
|
getPlatformGatewayConfig |
Returns configuration for a named gateway. |
|
STEP |
Use EnhancedPaymentGatewayService Primary user: Platform and domain services |
|
Method |
Purpose |
|
getSystemConfiguredGateways |
System-level configured gateways. |
|
getAvailableGatewaysForLandlord |
Gateways for one landlord. |
|
getAvailableGatewaysForLender |
Gateways for one lender. |
|
getAllAvailableGateways |
All scopes. |
|
isGatewaySystemConfigured |
Checks named gateway configuration. |
|
STEP |
Use LandlordPaymentGatewayService Primary user: Landlord payment flows |
|
Method |
Purpose |
|
getConfiguredGateway |
Returns the named or default landlord gateway. |
|
processPayment |
Initiates a landlord-context payment using the configured gateway. |
|
STEP |
Use PaymentGatewayConfigService Primary user: Configuration validation |
|
Method |
Purpose |
|
isGatewayConfigured |
Checks that a gateway has valid required configuration. |
|
getConfiguredGateways |
Returns configured gateways. |
|
getAvailableConfiguredGateways |
Returns configured gateways available to a landlord. |
|
isConfiguredForLandlord |
Validates one gateway for one landlord. |
|
getConfiguredGatewaysForLandlord |
Returns all landlord-configured gateways. |
20 Phase 5 - Real-Time Health Monitoring
|
STEP |
Monitor Gateway Health Primary user: SuperAdmin, technical and operations teams |
PaymentGatewayHealthService stores health results in GatewayHealthCheck and exposes current and historical indicators.
|
Method |
Purpose |
|
getHealthSummary |
Aggregated platform health. |
|
getGatewayHealthStatus |
Current status per gateway. |
|
checkGatewayHealth |
Checks a gateway by ID. |
|
getGatewayHealth |
Returns full health data. |
|
refreshGatewayHealth |
Forces one new check. |
|
refreshAllGatewayHealth |
Forces all configured checks. |
|
calculateUptime |
Calculates availability percentage. |
|
getAverageResponseTime |
Calculates average API latency. |
|
getTransactionCount |
Counts recent transaction attempts. |
|
getSuccessRate |
Calculates verified success percentage. |
|
getErrorCount |
Counts recent errors. |
|
getLastSuccessfulTransaction |
Returns latest verified success time. |
Figure 4. Gateway health metrics and states
|
|
Health thresholds must be configured The supplied scenario defines the metrics but not exact healthy, degraded or down thresholds. Set thresholds by provider, use case and business tolerance. |
21 Gateway Health States and Alerts
|
State |
Meaning |
Recommended routing action |
|
Healthy |
Metrics are within approved thresholds. |
Normal selection. |
|
Degraded |
Latency, success or errors exceed warning thresholds. |
Reduce priority or require caution. |
|
Down |
Unavailable, failing or circuit breaker open. |
Do not route new payments. |
|
Unknown |
Insufficient current health data. |
Use conservative policy or manual review. |
GatewayHealthChanged should fire when a gateway moves between operational states. Operations should record the reason, time, affected use cases and any automatic routing change.
Health review frequency
· Real-time or frequent checks for active production gateways.
· Daily review of latency, success rate and error trends.
· Weekly review of gateway comparison and incident count.
· Monthly review of cost, failover frequency and default priorities.
22 Phase 6 - Automatic Failover and Circuit Breaker
|
STEP |
Apply Automatic Failover Primary user: GatewayFailoverService |
GatewayFailoverService protects payments from repeated provider failure by recording outcomes, managing circuit-breaker state and selecting an alternative.
|
Method |
Purpose |
|
isGatewayHealthy |
Checks current eligibility. |
|
getFailoverGateway |
Selects the best healthy alternative. |
|
recordFailure |
Stores a failure and feeds the circuit breaker. |
|
recordSuccess |
Stores success and resets failure state as configured. |
|
getGatewayHealthStatus |
Returns health and breaker state. |
|
getAllGatewaysHealthStatus |
Returns user or landlord gateway states. |
|
resetCircuitBreaker |
Manually resets the breaker after recovery. |
|
forceFailover |
Routes a specific transaction to a selected alternative. |
Circuit-breaker sequence
1. The landlord gateway records a failure.
2. Failure count increases.
3. The configured threshold is evaluated.
4. When the threshold is exceeded, the breaker opens and the gateway becomes unhealthy.
5. The failover service selects the next eligible healthy gateway.
6. GatewayFailoverEvent records the failed and replacement gateways.
7. GatewayFailoverOccurred is fired.
8. Recovery testing occurs before normal routing resumes.
|
|
Failover must not create duplicate payment attempts Before retrying, determine whether the first provider definitely failed or may still complete asynchronously. Use provider references and idempotency controls. |
23 Failover Configuration and Audit
|
GatewayFailoverConfig item |
Purpose |
|
Failure threshold |
Number or rate of failures before the breaker opens. |
|
Retry policy |
Whether, when and how a transaction may be retried. |
|
Priority order |
Sequence of alternative gateways. |
|
Recovery interval |
Time before rechecking a failed gateway. |
|
Use-case restriction |
Which payment types may fail over. |
|
Country / currency restriction |
Which alternatives are legally and technically eligible. |
GatewayFailoverEvent should retain the original gateway, replacement gateway, transaction reference, failure reason, timestamps and result.
Manual reset checklist
|
☐ |
Provider status has recovered. |
|
☐ |
Credentials and configuration are valid. |
|
☐ |
A test connection passes. |
|
☐ |
A controlled transaction test passes where permitted. |
|
☐ |
Pending or uncertain transactions have been reconciled. |
|
☐ |
The reset is approved and recorded. |
24 Phase 7 - Client Gateway Selection
|
STEP |
Build the Client's Available Gateway List Primary user: Platform payment service |
Before a client starts a payment, the system filters the full gateway list.
1. Determine the payment use case.
2. Get platform gateways for the use case.
3. Get the landlord's configured gateways.
4. Apply property-level configuration where relevant.
5. Filter by client country.
6. Filter by currency and amount support.
7. Filter by gateway feature requirement such as recurring or direct debit.
8. Remove inactive, unconfigured, down or circuit-broken gateways.
9. Order by default, routing score or business rule.
10. Display only the final eligible options.
|
|
Do not expose a gateway because its logo exists The gateway must be active, configured, country-eligible, use-case compatible and operationally healthy. |
25 Client Payment Initiation, Callback and Verification
|
STEP |
Process a Client Payment Primary user: Client and platform payment service |
The client selects an eligible gateway. PaymentGatewayFactory resolves the provider implementation, and processPayment creates the provider session, link or intent.
Figure 5. Client payment journey
Payment data package
|
Data |
Purpose |
|
Transaction reference |
Unique Leaseora reference for the payment. |
|
Amount and currency |
Expected value and contractual currency. |
|
Client |
Payer identity and contact context. |
|
Landlord / property |
Recipient and business context. |
|
Payment type |
Rent, deposit, instalment, wallet, utility or other use case. |
|
Return URL |
Client browser return path. |
|
Webhook / callback URL |
Server-to-server notification path. |
|
Metadata |
Lease, sale, booking, property or invoice identifiers. |
Reference patterns from the supplied flows
|
Use case |
Example reference pattern |
|
Rent |
RENT-{leaseId}-{timestamp} |
|
Property purchase deposit |
PROP-DEP-{saleId}-{timestamp} |
|
Property purchase instalment |
PROP-INST-{saleId}-{timestamp} |
|
We Build For You deposit |
WB-DEP-{bookingId}-{timestamp} |
|
Other flows |
Use a unique module-specific prefix and stable business ID. |
26 Server-Side Verification and Idempotency
A browser return or success message is not sufficient evidence of payment. Leaseora should verify the provider transaction server-side.
|
☐ |
The provider reference matches the Leaseora transaction. |
|
☐ |
The provider status is successful or settled according to the flow. |
|
☐ |
The amount matches the expected amount. |
|
☐ |
The currency matches the expected currency. |
|
☐ |
The merchant or destination account is correct. |
|
☐ |
The payment type and metadata match the business record. |
|
☐ |
The transaction has not already been completed. |
|
☐ |
Any provider fee or net settlement is recorded separately where needed. |
Idempotency controls
· Use one unique Leaseora reference per intended payment attempt.
· Store the provider transaction ID.
· Treat repeated callbacks for the same provider transaction as one outcome.
· Do not create a second payout, receipt or business update on a duplicate callback.
· Use database transactions or locking around final payment completion.
· Keep pending or unknown states when the provider result is inconclusive.
|
|
Unknown is not failed A timeout can mean the provider response was not received even though the payment completed. Requery the provider before retrying or asking the client to pay again. |
27 Downstream Actions After Verified Payment
1. Update the correct payment or business record.
2. Record the provider transaction and status.
3. Record the amount, currency, fee and timestamps.
4. Update rent, sale, booking, wallet or utility balance.
5. Create or trigger LandlordPayout where the flow requires it.
6. Generate the client receipt or confirmation.
7. Notify the client and landlord.
8. Make the result available to reporting and analytics.
9. Reconcile the transaction with provider settlement and bank records.
|
|
Payment verification and payout are separate A verified client payment does not guarantee that provider settlement or landlord payout has completed. Track each stage independently. |
28 Lease-Specific Gateway Features
|
STEP |
Use LeasePaymentGatewayService Primary user: Lease and rent payment flows |
|
Method |
Purpose |
|
processLeasePayment |
Processes a standard rent payment. |
|
setupRecurringPayment |
Creates recurring rent collection where supported. |
|
processAutomaticRentCollection |
Charges the due amount automatically. |
|
processSplitPayment |
Splits payment across configured gateways or parties. |
|
processLateFee |
Charges an approved late fee. |
|
getPaymentHistory |
Returns lease payment history. |
|
refundPayment |
Processes full or partial refund. |
Recurring-payment setup checklist
|
☐ |
Gateway supports recurring payments in the relevant country. |
|
☐ |
Client has provided the required mandate or authorisation. |
|
☐ |
Amount or schedule is clearly defined. |
|
☐ |
Payment date, retries and cancellation rules are disclosed. |
|
☐ |
Provider token or mandate reference is stored securely. |
|
☐ |
Failed collection creates an actionable status, not an assumed payment. |
Refund controls
|
☐ |
Original transaction is verified and refundable. |
|
☐ |
Refund amount does not exceed available refundable amount. |
|
☐ |
Reason and approver are recorded. |
|
☐ |
Provider refund reference is stored. |
|
☐ |
Leaseora payment and payout records are updated appropriately. |
|
☐ |
Client communication is sent. |
|
|
Split payment needs exact reconciliation Where a payment is split across gateways or parties, each component should have its own reference, status, fee, recipient and settlement record. |
29 Utility, Lender and Government Gateway Flows
|
STEP |
Process Utility Bill Payments Primary user: UtilityPaymentGatewayService |
payUtilityBill uses the configured gateway to collect a utility invoice. The verified payment should update the utility invoice, unit balance and reconciliation record.
|
STEP |
Configure Lender Gateways Primary user: Lender user |
LenderPaymentGatewayController allows financing-marketplace lenders to create, edit, test, set default, activate, deactivate or remove their gateway configuration.
|
STEP |
Configure Government Agency Gateways Primary user: Government agency user / authorised administrator |
GovAgencyPaymentGateway provides a separate gateway context for government tax-remittance receipts and should remain segregated from landlord and client credentials.
|
|
Domain separation Landlord, lender and government gateway configurations should use separate accounts, permissions, audit trails and payout destinations. |
30 Phase 8 - Payment Gateway APIs
|
STEP |
Use the Payment Gateway REST API Primary user: Mobile and external integration teams |
|
Endpoint |
Purpose |
|
GET /api/payment-gateways/health |
Health status of all gateways. |
|
GET /api/payment-gateways/health/summary |
Aggregated health summary. |
|
GET /api/payment-gateways/routing |
Available routing options for a context. |
|
GET /api/payment-gateways/optimal |
Best gateway for the context. |
|
GET /api/payment-gateways/fallback |
Eligible fallback gateways. |
|
GET /api/payment-gateways/analytics |
Gateway analytics. |
|
POST /api/payment-gateways/health/refresh |
Force health refresh. |
|
GET /api/payment-gateways/{gatewayId}/health |
One gateway health check. |
API controls to implement and verify
|
☐ |
Authentication and authorisation scopes. |
|
☐ |
Environment separation. |
|
☐ |
Input validation for country, currency, amount and use case. |
|
☐ |
Rate limits and abuse protection. |
|
☐ |
No secret credentials in responses. |
|
☐ |
Consistent error codes and correlation IDs. |
|
☐ |
Audit logs for routing and health refresh. |
|
☐ |
Versioning and backward compatibility. |
|
|
Production API contract requires confirmation The supplied scenario lists routes and actions but not authentication, request schemas, response schemas, rate limits or error contracts. |
31 Specialised Mofi and Squad Gateways
|
STEP |
Manage Mofi Gateway Primary user: SuperAdmin Mofi domain |
Mofi\MofiPaymentGateway is the specialised model for Mofi integration and is managed through the SuperAdmin Mofi domain. Confirm its credential, routing, verification and payout rules separately.
|
STEP |
Manage Squad Gateway Primary user: SuperAdmin / landlord / mobile wallet flow |
Squad\SquadPaymentGateway and SquadGateway handle Nigeria-specific Squad operations. The supplied wallet flow includes Squad card tokenisation through Mobile\WalletController@initializeSquadTokenization.
|
|
Specialised models should still follow common controls Use the same encryption, environment, testing, health, verification, audit, reconciliation and incident standards unless the specialised provider requires stricter controls. |
32 Credential, Webhook and Data Security
Credential security controls
|
☐ |
Encrypt API and secret keys at rest. |
|
☐ |
Restrict decrypted access to server-side authorised services. |
|
☐ |
Use separate sandbox and production keys. |
|
☐ |
Rotate keys after exposure, employee departure or provider requirement. |
|
☐ |
Do not place secrets in URLs, browser code, screenshots or ordinary logs. |
|
☐ |
Use a secure secret-management process in deployment. |
Webhook controls
|
☐ |
Use HTTPS. |
|
☐ |
Verify provider signature or authenticity mechanism. |
|
☐ |
Validate timestamp or replay protection where supported. |
|
☐ |
Validate reference, amount, currency and merchant account. |
|
☐ |
Store raw provider event ID for idempotency. |
|
☐ |
Acknowledge quickly and process heavy work asynchronously where appropriate. |
|
☐ |
Log safe metadata and correlation IDs. |
|
☐ |
Retry failed processing without duplicating business actions. |
|
|
Card-data boundary Leaseora should use provider-hosted checkout or approved tokenisation so raw card data is not unnecessarily stored or processed by the application. Exact compliance obligations depend on the deployed architecture and provider contract. |
33 Fee, Settlement, Payout and Reconciliation Controls
|
Financial element |
What must be tracked |
|
Gross payment |
Amount paid by the client. |
|
Gateway fee |
Percentage, flat fee or provider charge. |
|
Platform fee |
Leaseora service fee where applicable. |
|
Net provider settlement |
Amount sent by the gateway. |
|
Landlord payout |
Amount and status transferred to the landlord. |
|
Refund |
Amount returned and provider reference. |
|
Chargeback / reversal |
Disputed or reversed provider amount. |
|
FX difference |
Conversion impact where currencies differ. |
Daily reconciliation sequence
1. Compare Leaseora verified transactions with provider transactions.
2. Review pending, failed and unknown statuses.
3. Compare provider settlement with bank receipt.
4. Compare landlord payouts with payout records.
5. Review refunds, reversals and chargebacks.
6. Reconcile gateway fees and net amounts.
7. Investigate duplicates or missing callbacks.
8. Close only when differences are explained or carried as open items.
|
|
Authorised does not always mean settled Define which provider status is used for business completion and which status is used for financial settlement and payout. |
34 Gateway Analytics Definitions
|
Metric |
Definition |
|
Attempted transactions |
All payment initiation attempts. |
|
Verified successful transactions |
Transactions confirmed successful by provider verification. |
|
Pending / unknown |
Transactions without a final verified outcome. |
|
Success rate |
Verified successes divided by the defined attempt population. |
|
Average response time |
Average provider API latency. |
|
Error rate |
Failed or errored requests divided by attempts. |
|
Transaction volume |
Total transaction value in original or reporting currency. |
|
Gateway cost |
Provider fees and associated payment cost. |
|
Failover rate |
Transactions moved to an alternative gateway. |
|
Recovery time |
Time from gateway degradation to restored service. |
|
|
Document the denominator A success-rate comparison is misleading unless every gateway uses the same definition of attempt, success, duplicate, retry, refund and reporting period. |
35 AI Recommendations and Human Review
System and landlord recommendation endpoints can suggest gateway configuration or routing changes based on transaction patterns, error rates, response time and cost.
|
Recommendation type |
Use |
|
Preferred gateway by country |
Uses country-specific performance and availability. |
|
Preferred gateway by use case |
Separates wallet, rent, payout and service-payment performance. |
|
Default-gateway change |
Suggests a better primary option. |
|
Failover-priority change |
Suggests a more reliable fallback order. |
|
Cost optimisation |
Balances fees against success and failure cost. |
|
Configuration issue |
Identifies recurring authentication or setup errors. |
|
|
AI recommendation is advisory Before applying a change, review provider contract, country, regulatory eligibility, current incidents, recurring mandates, client experience and reconciliation impact. |
36 Incident Response and Service Recovery
Figure 6. Gateway incident-response runbook
Incident severity indicators
|
Indicator |
Possible severity |
|
Single client validation error |
Low; likely data or client-specific. |
|
Error spike for one landlord |
Medium; landlord credentials or provider account. |
|
Gateway degraded across countries |
High; provider or platform issue. |
|
Duplicate payments or payouts |
Critical financial-control issue. |
|
Credential exposure |
Critical security incident. |
|
Callbacks failing across modules |
High or critical, depending on transaction impact. |
Client communication principles
· State the payment status accurately: successful, failed, pending or under review.
· Do not ask the client to repay until the first attempt is verified.
· Provide the Leaseora reference and expected review time.
· Confirm when a refund, retry or alternative gateway is available.
· Avoid exposing provider secrets or internal security details.
37 Testing and Validation Tools
|
STEP |
Run Gateway Tests Primary user: Technical and operations teams |
|
Tool |
Purpose |
|
TestCompleteGatewayWorkflow |
End-to-end initiation, verification and payout test. |
|
TestSystemGateways |
Connectivity test for all configured platform gateways. |
|
SuperAdmin testGatewayConnection |
Platform credential and connectivity check. |
|
Landlord testConnection |
Landlord credential and connectivity check. |
|
Lender testConnection |
Lender credential and connectivity check. |
Minimum test cases per gateway
|
☐ |
Valid sandbox payment. |
|
☐ |
Invalid credentials. |
|
☐ |
Unsupported country. |
|
☐ |
Unsupported currency. |
|
☐ |
Provider timeout. |
|
☐ |
Declined payment. |
|
☐ |
Repeated callback. |
|
☐ |
Incorrect amount or currency in callback. |
|
☐ |
Pending or delayed provider result. |
|
☐ |
Refund. |
|
☐ |
Recurring setup where supported. |
|
☐ |
Payout or withdrawal where supported. |
|
☐ |
Circuit-breaker trip and failover. |
|
☐ |
Recovery and breaker reset. |
|
|
Never use an uncontrolled live charge for testing Use sandbox or provider-approved low-risk production testing with documented accounts, amounts and refund procedures. |
38 Deployment and Change Management
|
☐ |
Platform gateway record approved. |
|
☐ |
Sandbox and production credentials separated. |
|
☐ |
Provider account, country and currencies approved. |
|
☐ |
Webhook URLs registered and verified. |
|
☐ |
Health thresholds configured. |
|
☐ |
Failover threshold and priority configured. |
|
☐ |
Landlord access and property assignment confirmed. |
|
☐ |
Client payment screens tested. |
|
☐ |
Callbacks and webhooks tested for idempotency. |
|
☐ |
Reconciliation and settlement process documented. |
|
☐ |
Support and incident owners assigned. |
|
☐ |
Rollback plan prepared. |
Production change process
1. Document the reason for the change.
2. Identify affected gateways, landlords, properties and clients.
3. Test in sandbox.
4. Review security and financial controls.
5. Approve the change.
6. Deploy during a controlled window.
7. Monitor health and payment outcomes.
8. Reconcile transactions after the change.
9. Close with evidence or roll back.
39 Production Sign-Off Requirements
|
Area |
Sign-off requirement |
|
Gateway record |
Name, environment, scope, country and feature settings are correct. |
|
Credentials |
Encrypted, valid, tested and owned by the correct account. |
|
Routing |
Country, property, use-case and health filters work. |
|
Verification |
Server-side amount, currency, reference and status checks work. |
|
Idempotency |
Duplicate callbacks do not duplicate payment, payout or receipt. |
|
Failover |
Threshold, alternative order and audit log work. |
|
Health |
Metrics and state changes are visible. |
|
Analytics |
Definitions and currency basis are documented. |
|
Refunds |
Full and partial refund process is controlled. |
|
Reconciliation |
Provider, bank, payout and business records reconcile. |
|
Security |
Secrets, webhooks and permissions are protected. |
|
Support |
Incident, uncertain payment and client communication procedures are trained. |
|
|
Go-live decision Do not enable production traffic until end-to-end payment, callback, verification, payout and reconciliation have passed for the intended use case. |
40 Key Backend Models Reference
|
Model |
Purpose |
|
PaymentGateway |
Core platform gateway, encrypted credentials, scope, countries, features, fees and active status. |
|
LandlordGateway |
Landlord-specific credentials, default, active status and success/failure tracking. |
|
UserPaymentGateway |
Links a landlord or user to an enabled gateway. |
|
PropertyPaymentGateway |
Links a property to allowed gateways. |
|
GatewayHealthCheck |
Stores health results. |
|
GatewayFailoverConfig |
Stores thresholds, retry and priority rules. |
|
GatewayFailoverEvent |
Stores each failover occurrence. |
|
GovAgencyPaymentGateway |
Government tax-remittance gateway. |
|
MofiPaymentGateway |
Mofi-specific gateway model. |
|
SquadPaymentGateway |
Squad-specific gateway model. |
41 Controllers and Services Reference
|
Controller |
Purpose |
|
SuperAdmin\Core\PaymentGatewayController |
Platform gateway registration, advanced configuration, landlord access, analytics and health. |
|
Landlord\Shared\PaymentGatewayController |
Landlord configuration, testing, defaults, health and analytics. |
|
API\PaymentGatewayAPIController |
Health, routing, optimal gateway, fallback and analytics API. |
|
API\PaymentGatewayHealthController |
Health summary and per-gateway check. |
|
Lender\LenderPaymentGatewayController |
Lender gateway configuration. |
|
Government\GovAgencyPaymentGatewayController |
Government agency gateway configuration. |
|
PropertyPaymentController |
Property-level gateway assignment. |
|
Service |
Purpose |
|
PaymentGatewayFactory |
Resolves the gateway implementation. |
|
GatewayRouterService |
Selects and routes to the optimal gateway. |
|
LeaseoraGatewayRouter |
Routes Leaseora-native payments. |
|
PlatformPaymentGatewayService |
Use-case-based platform gateway availability. |
|
EnhancedPaymentGatewayService |
Cross-scope gateway availability. |
|
LandlordPaymentGatewayService |
Landlord-specific processing. |
|
PaymentGatewayConfigService |
Configuration validation. |
|
PaymentGatewayHealthService |
Health monitoring. |
|
GatewayFailoverService |
Circuit breaker and failover. |
|
PaymentGatewayAnalyticsService |
Performance, cost and error analytics. |
|
LeasePaymentGatewayService |
Rent, recurring, split, late fee and refund. |
|
UtilityPaymentGatewayService |
Utility bill payment. |
42 Events and Test Commands Reference
|
Event |
Trigger |
|
PaymentGatewayStatusChanged |
Gateway activated or deactivated. |
|
GatewayHealthChanged |
Health state changes. |
|
GatewayFailoverOccurred |
Failover selects an alternative. |
|
Console command |
Purpose |
|
TestCompleteGatewayWorkflow |
Runs initiation, verification and payout test. |
|
TestSystemGateways |
Tests all configured system gateways. |
The exact listener, notification, queue and retry configuration for these events and commands should be confirmed in the deployed implementation.
43 Worked Example - Rent Payment with Automatic Failover
|
|
Scenario A client in Nigeria pays monthly rent for a property configured with Paystack as default and Flutterwave as fallback. Paystack becomes unavailable during checkout. |
|
Stage |
What happens |
|
1. Platform setup |
SuperAdmin registers Paystack and Flutterwave, sets countries and activates both. |
|
2. Landlord access |
Both gateways are enabled for the landlord. |
|
3. Landlord configuration |
The landlord enters valid credentials, tests both and sets Paystack as default. |
|
4. Property assignment |
The property allows Paystack and Flutterwave. |
|
5. Client options |
The Nigeria client sees eligible gateways. |
|
6. Payment context |
Leaseora creates a RENT reference with lease, amount and currency metadata. |
|
7. Primary initiation |
PaymentGatewayFactory resolves PayStackGateway and processPayment creates the session. |
|
8. Provider failure |
The provider call fails and LandlordGateway@markFailure records the failure. |
|
9. Circuit breaker |
The configured threshold is reached and Paystack becomes unhealthy. |
|
10. Alternative selection |
GatewayFailoverService selects Flutterwave. |
|
11. Failover audit |
GatewayFailoverEvent is stored and GatewayFailoverOccurred is fired. |
|
12. New session |
FlutterwaveGateway creates a new provider session using a controlled retry reference. |
|
13. Client authorisation |
The client completes the Flutterwave checkout. |
|
14. Server verification |
Leaseora verifies status, amount, currency, merchant and metadata. |
|
15. Business update |
The rent payment is recorded and the lease schedule is updated. |
|
16. Payout |
The configured landlord payout flow is triggered. |
|
17. Notifications |
Client and landlord receive payment confirmation. |
|
18. Reconciliation |
Finance reconciles the provider transaction, settlement, payout and gateway fees. |
|
19. Recovery |
Paystack is tested before the circuit breaker is reset. |
|
|
Critical safeguard The system must confirm that the Paystack attempt did not complete before creating a second charge on Flutterwave. |
44 User Acceptance Testing and Go-Live Checklist
|
Test area |
Acceptance test |
|
Platform registration |
Create every gateway with correct scope, environment and country rules. |
|
Encryption |
Confirm credentials are not stored or returned in plaintext. |
|
Landlord enablement |
Enable and disable one gateway for one and multiple landlords. |
|
Landlord configuration |
Create, edit, activate, deactivate and set default. |
|
Connection test |
Test valid and invalid credentials. |
|
Property assignment |
Verify only assigned options appear. |
|
Country filter |
Test supported and unsupported countries. |
|
Use-case filter |
Test wallet, rent, service, subscription and payout pools. |
|
Factory |
Resolve each gateway class. |
|
Routing |
Test amount, currency, property, country and health conditions. |
|
Payment initiation |
Create a valid session or link. |
|
Callback |
Process return and server webhook. |
|
Verification |
Reject wrong amount, currency, merchant or metadata. |
|
Idempotency |
Replay callback and confirm no duplicate actions. |
|
Pending status |
Handle timeout or unknown result safely. |
|
Health |
Create healthy, degraded and down conditions. |
|
Circuit breaker |
Trip at the configured threshold. |
|
Failover |
Select the expected alternative. |
|
Recovery |
Reset only after successful tests. |
|
Recurring |
Create, process, fail and cancel where supported. |
|
Split payment |
Verify each component and recipient. |
|
Refund |
Test full and partial refund. |
|
Payout |
Test provider or bank payout where supported. |
|
Analytics |
Verify volume, success, latency, cost and error definitions. |
|
API |
Test authentication, validation, rate limit and permissions. |
|
Incident |
Run a controlled outage simulation. |
|
Reconciliation |
Match provider, bank, payout and business records. |
|
|
Pilot scope Start with one country, one landlord, one property, one payment use case and at least one tested fallback before wider rollout. |
45 Common Issues and Troubleshooting
|
Issue |
Recommended action |
|
Gateway does not appear for the landlord |
Check platform scope, landlord enablement, active status and UserPaymentGateway. |
|
Gateway appears but cannot be saved |
Check required credentials and landlord scope. |
|
Connection test fails |
Review environment, credentials, provider account, network and API permissions. |
|
Client cannot see a gateway |
Check property assignment, country, use case, active status and health. |
|
Payment session is not created |
Review factory mapping, payload validation, provider response and timeout. |
|
Browser says successful but Leaseora is pending |
Wait for or verify server-side provider result. |
|
Callback is processed twice |
Add or repair provider-event and transaction idempotency. |
|
Payment amount is wrong |
Review metadata, currency conversion and business-record amount. |
|
Gateway is marked down incorrectly |
Review health data, thresholds and provider status. |
|
Failover did not happen |
Check breaker threshold, eligible alternatives, country and use case. |
|
Failover created a duplicate charge |
Stop retries, verify both providers, refund duplicate under approval and review idempotency. |
|
Landlord payout is missing |
Confirm payment verification, payout trigger, gateway capability and payout status. |
|
Refund failed |
Check refundable amount, provider status, credentials and settlement. |
|
Recurring charge failed |
Review mandate, token, gateway support, amount and due date. |
|
Analytics totals differ |
Confirm period, currency, attempt definition, duplicate handling and verification status. |
|
Provider settlement does not match |
Review fees, refunds, reversals, FX and settlement timing. |
46 Frequently Asked Questions
Can every landlord use every gateway?
No. The gateway must support landlord scope, be enabled by SuperAdmin, configured by the landlord and eligible for the property, country and use case.
Are gateway credentials encrypted?
The supplied PaymentGateway model uses encrypted setters and decrypted accessors.
Can one property use different gateways from another?
Yes. PropertyPaymentGateway controls property-level availability.
Can the client select a gateway?
Yes, from the final eligible list. Routing may also select the best option according to the flow.
Does a successful redirect prove payment?
No. Leaseora should verify the transaction with the provider server-side.
What happens when a gateway fails?
The failure is recorded, the circuit breaker may trip and an eligible healthy alternative can be selected.
Can failover always retry automatically?
Only when configured and safe. Uncertain first attempts must be verified to avoid duplicate charging.
Can Leaseora collect rent automatically?
LeasePaymentGatewayService supports recurring setup and automatic collection through gateways marked as recurring-capable.
Can payments be split?
The supplied lease gateway service includes split-payment processing.
Can a payment be refunded?
The supplied service includes full or partial refund processing.
Can payment health be accessed through API?
Yes. Health, routing, optimal, fallback and analytics endpoints are specified.
Can lenders configure gateways?
Yes. LenderPaymentGatewayController provides separate configuration.
Can government agencies receive tax remittances?
The supplied design includes GovAgencyPaymentGateway.
Which gateway is cheapest?
Use cost analysis together with success rate, latency, country support and failure impact.
Does Leaseora guarantee provider uptime?
No. It monitors health and can fail over, but provider and banking availability remain external dependencies.
47 Technical Matters to Confirm Before Production
|
Area |
Confirmation required |
|
Credential storage |
Confirm encryption keys, rotation, environment secrets and access logging. |
|
Provider implementations |
Confirm exact methods supported by every concrete gateway class. |
|
Feature matrix |
Validate recurring, direct debit, withdrawal and tokenisation by provider account and country. |
|
Health thresholds |
Define healthy, degraded, down and unknown thresholds. |
|
Circuit breaker |
Define failure window, threshold, recovery and reset policy. |
|
Retry safety |
Define when a transaction is definitely failed and safe to retry. |
|
Idempotency |
Define provider event IDs, Leaseora references and database locking. |
|
Webhook security |
Confirm signature, replay protection and IP or domain controls. |
|
Settlement status |
Define which provider status updates the business record and which confirms settlement. |
|
Refunds |
Confirm provider-specific partial refund and fee treatment. |
|
Chargebacks |
Confirm dispute, reversal and balance-recovery workflow. |
|
Payouts |
Confirm method, timing, retries, fees and failed payout handling. |
|
FX |
Confirm source rate, markup, rounding and reporting. |
|
Recurring |
Confirm mandate, token, schedule, retry and cancellation rules. |
|
Split payment |
Confirm split components, fees, recipient settlement and reversal. |
|
API |
Confirm authentication, request schemas, response schemas, rate limits and versioning. |
|
Logging |
Confirm redaction, retention, correlation IDs and searchable audit fields. |
|
Data residency |
Confirm external provider, AI and payment-data processing locations. |
|
PCI and regulatory scope |
Confirm the deployed card-data and payment-regulation obligations. |
|
Business continuity |
Confirm fallback providers by country, currency and use case. |
|
|
Do not assume provider parity The common interface standardises Leaseora's code, but providers still differ in status models, webhooks, fees, settlement, refunds, recurring payments and country availability. |
48 Quick Reference - 26-Step Operating Flow
1. Register the gateway at platform level.
2. Encrypt and store sandbox or production credentials.
3. Set gateway scope, countries, features, fees and active status.
4. Configure advanced webhook, timeout, retry, health and failover settings.
5. Enable the gateway for the appropriate landlord.
6. Landlord enters landlord-specific credentials where required.
7. Test the landlord connection.
8. Activate the landlord gateway and set a default if appropriate.
9. Assign gateways to properties.
10. Review analytics, cost, errors and recommendations.
11. Monitor health and store GatewayHealthCheck records.
12. Filter client options by use case, landlord, property, country, feature and health.
13. Generate a unique transaction reference.
14. Resolve the provider implementation through PaymentGatewayFactory.
15. Route and initiate the payment.
16. Redirect the client or create the required mandate or provider session.
17. Receive the client return and provider webhook.
18. Verify reference, status, amount, currency, merchant and metadata server-side.
19. Apply idempotency and complete the business record only once.
20. Trigger payout, receipt and notifications when required.
21. Record success or failure against the landlord gateway.
22. Trip the circuit breaker when the threshold is exceeded.
23. Select a safe healthy failover gateway when permitted.
24. Reconcile provider, bank, payout, refund and business records.
25. Review gateway analytics, incidents and health trends.
26. Test changes and complete controlled production sign-off.
|
|
Business value Leaseora's Payment Gateway module gives a real estate company resilient, country-aware and use-case-aware payment orchestration with encrypted credentials, landlord and property controls, provider abstraction, verification, health monitoring, failover, analytics and operational audit. |
LEASEORA
PAYMENT GATEWAY MANAGEMENT
Configure, route, verify, monitor and recover real estate payments from one connected gateway layer.
|
|
Support and onboarding For gateway onboarding, landlord configuration, property assignment, sandbox testing, incident support or integration assistance, contact Leaseora through support@leaseora.com. |
leaseora.com
Was this article helpful?
Your feedback helps us improve our documentation.