Overview
The NearPay POS Integration module provides a complete solution for integrating NearPay payment terminals with Odoo 18 Point of Sale through a Flutter mobile application. This module enables seamless payment processing, customer display management, and receipt printing via NearPay's SDK.
Built specifically for Tunisia's payment ecosystem, this integration supports real-time payment processing with comprehensive transaction logging and customer interaction features.
Key Features
Payment Processing
Direct integration with NearPay SDK for secure payment processing. Supports both regular payments and invoice payments with real-time transaction validation.
Flutter Bridge
Seamless communication between Odoo POS and Flutter mobile app using WebView JavaScript bridge for payment commands and responses.
Customer Display
Dynamic customer-facing display with welcome screens, payment processing indicators, and thank you messages with beautiful animations.
Auto Receipt Printing
Automatic receipt generation and printing via Flutter app with detailed transaction information and payment method details.
Transaction Logging
Complete JSON response data storage for audit trails, reporting, and transaction reconciliation with timestamped records.
Real-time Processing
Instant payment validation with error handling, timeout management, and fallback mechanisms for reliable operation.
Technical Specifications
Architecture Components:
- Frontend: JavaScript module patching Odoo POS screens
- Backend: Python controllers for display and PDF generation
- Models: Extended POS models for NearPay data storage
- Bridge: Flutter WebView communication layer
- API: RESTful endpoints for payment processing
Requirements
- Odoo Community/Enterprise 18.0 - Point of Sale module installed and configured
- Flutter Mobile Application - With NearPay SDK integration and WebView support
- NearPay Terminal - Active NearPay merchant account and compatible terminal
- Network Connection - Stable internet connection for payment processing
- Mobile Device - Android/iOS device running the Flutter application
Installation & Configuration
- Download and install the module in your Odoo 18 installation
- Update the apps list and install "NearPay POS Integration"
- Configure your POS settings and add NearPay payment methods
- Deploy your Flutter application with NearPay SDK integration
- Configure the WebView bridge settings in your mobile app
- Test 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 Payment from Browser Console:
- Open Odoo POS in your browser
- Create an order with products and select NearPay payment method
- Open browser Developer Tools (F12)
- Go to Console tab
- Paste and execute the following JavaScript code:
paymentComplete({
id: "19f9524d-407a-4d28-bd1e-89e7fb821598",
transaction_uuid: "11d91e8b-fe1a-44c8-a4c7-eab8aab9f62a",
merchant: {
id: "100000000000001",
name: { arabic: "123455", english: "NearPay-Test Terminal INMA" },
address: { arabic: "4321", english: "KAFD" },
category_code: "0763"
},
card_scheme: { name: { english: "Visa", arabic: "فيزا" }, id: "VC" },
card_scheme_sponsor: "INMA",
start_date: "06/11/2022",
start_time: "16:11:09",
end_date: "06/11/2022",
end_time: "16:11:09",
tid: "0200010400000104",
system_trace_audit_number: "000043",
pos_software_version_number: "1.0.0",
retrieval_reference_number: "000000002031",
transaction_type: { name: { arabic: "شراء", english: "PURCHASE" }, id: "00" },
is_approved: true,
is_refunded: false,
is_reversed: false,
approval_code: { value: "587117", label: { arabic: "رمز الموافقة", english: "Approval Code" } },
action_code: "000",
status_message: { arabic: "مقبولة", english: "Approved" },
pan: "4639 17** **** 3838",
card_expiration: "23/02",
amount_authorized: { label: { arabic: "مبلغ الشراء", english: "PURCHASE AMOUNT" }, value: "0.01" },
amount_other: { label: { arabic: "مبلغ النقد", english: "NAQD AMOUNT" }, value: "0.00" },
currency: { arabic: "ر.س", english: "SAR" },
verification_method: { english: "NO VERIFICATION REQUIRED", arabic: "لا يتطلب التحقق" },
receipt_line_one: { arabic: "", english: "" },
receipt_line_two: { arabic: "", english: "" },
thanks_message: { arabic: "شكرا لاستخدامكم مدى", english: "Thank you for using mada" },
save_receipt_message: { arabic: "يرجى الاحتفاظ بالفاتورة", english: "please retain receipt" },
entry_mode: "CONTACTLESS",
application_identifier: "A0000000031010",
terminal_verification_result: "2480403800",
transaction_state_information: "0000",
cardholader_verfication_result: "1F0000",
cryptogram_information_data: "80",
application_cryptogram: "1D6B44271DC4A690",
kernel_id: "03",
payment_account_reference: "",
pan_suffix: "",
qr_code: "https://sandbox-api.nearpay.io/ui/receipt/19f9524d-407a-4d28-bd1e-89e7fb821598"
});
This will simulate a successful NearPay transaction and complete the payment in Odoo POS.
📚 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. Order Creation
Customer places order in Odoo POS, selects NearPay payment method.
2. Payment Request
POS sends payment request to Flutter app via WebView bridge.
3. NearPay Processing
Flutter app communicates with NearPay SDK for terminal processing.
4. Response Handling
Payment result returned to POS with complete transaction data.
5. Order Completion
Order validated, receipt printed, and customer display updated.
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 integration.
What's Included:
- Complete module source code
- Installation and configuration guide
- Flutter app integration examples
- API documentation
- Console testing utilities
- Technical support via email
- Updates for Odoo 18.x versions
Please log in to comment on this module