Overview
The NearPay Invoice Payment Integration module provides a complete solution for processing invoice payments through NearPay payment terminals integrated with Odoo 18 Accounting via a Flutter mobile application. This module enables seamless payment processing directly from the invoice payment wizard with comprehensive transaction tracking.
Built specifically for mobile payment ecosystems, this integration supports real-time payment processing with comprehensive transaction logging, automatic payment reconciliation, and detailed transaction metadata storage.
Key Features
Invoice Payment Processing
Direct integration with NearPay SDK for secure invoice payment processing. Supports single and batch invoice payments with real-time transaction validation and automatic reconciliation.
Flutter WebView Bridge
Seamless communication between Odoo Accounting and Flutter mobile app using WebView JavaScript bridge for payment commands, responses, and transaction callbacks.
Auto Reconciliation
Automatic payment creation and reconciliation with invoices. Payment records are automatically posted and reconciled with outstanding receivables.
Pre-Flight Validation
Comprehensive validation before initiating NearPay transaction to prevent charging customers when payment cannot be processed. Includes invoice state checks and amount validation.
Transaction Metadata
Complete storage of NearPay transaction data including card details (masked), approval codes, retrieval references, merchant IDs, and terminal information for audit trails.
Real-time Processing
Instant payment validation with error handling, duplicate transaction detection, timeout management, and comprehensive logging for debugging and support.
Technical Specifications
Architecture Components:
- Frontend: OWL component for payment wizard interface
- Backend: Python wizard extension for payment registration
- Models: Extended payment models for NearPay metadata storage
- Bridge: Flutter WebView communication layer with callback pattern
- API: JSON-RPC endpoints for logging and health checks
- Validation: Pre-flight checks to prevent failed transactions
Requirements
- Odoo Community/Enterprise 18.0 - Accounting module installed and configured
- Flutter Mobile Application - With NearPay SDK integration and WebView support
- NearPay Terminal - Active NearPay merchant account and compatible terminal device
- Network Connection - Stable internet connection for payment processing and API calls
- Mobile Device - Android/iOS device running the Flutter application with terminal connectivity
Installation & Configuration
- Download and install the module in your Odoo 18 installation
- Update the apps list and install "Account Invoice Webview NearPay Bridge"
- The module automatically adds NearPay payment methods to all bank journals
- Deploy your Flutter application with NearPay SDK integration
- Configure the WebView bridge settings in your mobile app to load Odoo web interface
- Test invoice payment processing with your NearPay terminal
Payment Method Configuration:
Testing & Development
🚨 Console Testing Instructions
For Development and Testing Purposes Only
⚠️ Important Notice
The following console testing method is intended for development, debugging, and testing purposes only. Do not use this in production environments.
How to Test Invoice Payment from Browser Console:
- Open an invoice in Odoo Accounting
- Click "Register Payment" and select NearPay payment method
- The payment bridge interface will open
- Open browser Developer Tools (F12)
- Go to Console tab
- Use the test helper function:
// Test successful payment window.testInvoicePayment(true); // Test declined payment window.testInvoicePayment(false);
Or manually trigger with complete transaction data:
window.paymentComplete({
"receipts": [{
"receipt_id": "907c9378-3d04-4518-8256-b891d8f1d408",
"transaction_uuid": "e310f010-2d0f-4908-8625-07c336107942",
"merchant": {
"id": "100000000000001",
"name": { "english": "Test Merchant" }
},
"tid": "0209476200094762",
"retrieval_reference_number": "579690000000",
"card_scheme": {
"name": { "english": "mada" }
},
"pan": "4323 28** **** 2272",
"card_expiration": "26/06",
"amount_authorized": {
"value": "190.50"
},
"currency": { "english": "SAR" },
"status_message": { "english": "Approved" },
"is_approved": true,
"is_refunded": false,
"is_reversed": false,
"approval_code": { "value": "181422" },
"verification_method": { "english": "NO VERIFICATION REQUIRED" },
"entry_mode": "CONTACTLESS",
"qr_code": "https://sandbox-api.nearpay.io/ui/receipt/907c9378-3d04-4518-8256-b891d8f1d408"
}]
});
📚 NearPay Transaction Receipt Documentation
The transaction receipt format follows NearPay's official SDK models specification. For complete documentation on transaction receipt structure and all available fields, visit:
Official Documentation: https://docs.nearpay.io/en/guides/sdk-models#transaction-receipt
Workflow Process
1. Invoice Selection
User opens invoice(s) and clicks "Register Payment" from Odoo Accounting interface.
2. Payment Method Selection
User selects bank journal and chooses "NearPay" as the payment method in the payment wizard.
3. Pre-Flight Validation
System validates invoice status, amount, and payment configuration before initiating NearPay transaction.
4. Mobile Payment Bridge
JavaScript bridge sends payment request to Flutter app via WebView handler with invoice details.
5. NearPay Processing
Flutter app communicates with NearPay SDK for terminal processing and customer card interaction.
6. Transaction Callback
Payment result returned to Odoo via window.paymentComplete() callback with complete transaction data.
7. Payment Recording
Backend creates account.payment record, stores NearPay metadata, posts entry, and reconciles with invoice.
8. Completion
User is redirected to invoice list, payment is marked as completed, and transaction is logged for audit.
Transaction Data Storage
Every NearPay payment stores comprehensive transaction metadata on the account.payment record:
- Transaction Identifiers: UUID, receipt ID, retrieval reference number, reversal reference
- Amount Information: Authorized amount, currency with multi-language support
- Card Details: Masked card number, expiry date, card scheme (mada/Visa/Mastercard), entry mode
- Transaction Status: Approval code, verification method, status flags (approved/refunded/reversed)
- Merchant Data: Merchant ID, terminal ID (TID), system trace audit number
- Receipt Information: QR code URL for digital receipt access
- Raw Payload: Complete JSON transaction data for audit and debugging purposes
Safety Features
Duplicate Prevention
Transaction UUIDs are checked to prevent duplicate payment recording. The system detects and rejects already-processed transactions.
Invoice State Validation
Pre-flight and post-transaction validation ensures invoices are in valid state (posted, unpaid) before processing.
Amount Verification
Payment amount is validated against invoice amount due to prevent overpayment or incorrect amounts.
Error Recovery
If payment fails after customer charge, system provides refund instructions with transaction ID for manual reversal.
Health Monitoring
Periodic health checks during payment to detect wizard deletion or invoice status changes.
Comprehensive Logging
All events logged to server and console for debugging, audit trails, and technical support.
Support & Documentation
For technical support, customization requests, or additional features, please contact our development team. We provide comprehensive support for installation, configuration, and customization of the NearPay invoice payment integration.
What's Included:
- Complete module source code with detailed comments
- Installation and configuration guide
- Flutter app integration documentation
- API and callback documentation
- Console testing utilities for development
- Technical support via email and phone
- Updates and bug fixes for Odoo 18.x versions
- Integration with custom Flutter applications
Please log in to comment on this module