Release V5.2.6
Terminal Device Support
We've expanded the range of supported payment terminal devices:
User Interface Improvements
Enhanced display and interaction experience on Sunmi terminals:
- Sunmi Terminal UI Optimization (UP-722)
- Removed A-Z Button from Enter Transaction ID Screen (UP-884)
- Optimized Receipt Display for Sunmi P3 Mix Terminals (UP-942)
- Optimized transaction response delivery on Sunmi terminals (GA-1842)
Added Support for New Sunmi Terminal Models
Context: Users were limited to working with only a few Sunmi terminal models such as P2 SmartPad and P2 SE, preventing the use of newer models for payment processing. Additionally, newer SDK version 5.0 required support for different interfaces for receipt printing and error handling.
Solution: Implemented comprehensive support for Sunmi P3, P2 Lite SE, and P3 Mix terminal models with Kernel 100. Created architecture to support both old and new SDK versions using an interface approach, mapped error codes for the new SDK, and updated the terminal application to use the latest SDK libraries.
Impact: Merchants can now utilize these newer Sunmi terminal models for processing payments, providing more hardware options and ensuring continued operations as older models reach end-of-life. Full functionality is available including proper receipt printing and comprehensive error handling across all supported models.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: Terminal model classifier updated to recognize new models: P3, P2 Lite SE, and P3 Mix
- Code Changes: Added support for SDK version 5.0 interfaces alongside existing SDK support
- Filesystem Changes: Updated SDK library from PayLib-release-1.4.49.aar to PayLib-release-2.0.18.aar
- Data Migration: None
Implementation Actions
- Added new terminal models to the terminal classification system
- Implemented interface-based approach for SDK version compatibility
- Created error code mapping for new SDK to ensure proper error processing
- Updated scanner module configuration to support both older and newer package names
- Modified terminal application build configuration to support new models
- No manual Update Actions are required as all changes are implemented through standard code deployment
Configuration and Access Steps
- Obtain physical P3, P2 Lite SE, and P3 Mix terminals for testing
- Ensure terminals have ROM version requirements:
- P3 terminals: ROM version 3.0.18 with SPHS 5.0.38 or higher
- P3 Mix and P2 Lite SE: latest available firmware (minimum 4.1.22)
- Verify each terminal is in dev mode for testing
- Install the latest terminal application on each device
- Navigation: Settings → System Info → Device Info
Test Scenarios
-
Terminal Model Recognition
- Steps: Check device information in settings menu
- Expected result: The system correctly identifies each terminal model (P3, P2 Lite SE, P3 Mix)
-
Transaction Processing
- Steps: Process contact, contactless, and magstripe transactions on each terminal model
- Expected result: All transaction types complete successfully regardless of terminal model
-
Receipt Printing
- Steps: Process a transaction that generates a receipt on each terminal model
- Expected result: Receipts print correctly on each device with proper formatting
- Note: P3 Mix prints use 80mm receipts (wider than standard 58mm)
-
Error Handling
- Steps: Trigger various error conditions (scanner module missing, connection issues)
- Expected result: Readable error messages are displayed correctly with proper error code mapping
-
Scanner Functionality
- Steps: Open scanner and scan QR code on each terminal model
- Expected result: Scanner module correctly initializes and processes QR codes
Common Issues
- Scanner module may require ROM update on some models
- Verify scanner module package detection works correctly
- Check for proper screen adaptation on P2 Lite SE's two screen variants (FW: 355×662, HD: 391×648)
- Ensure receipt formatting is correct on P3 Mix's wider 80mm printer
- Validate application behavior with different SPHS versions (5.0.x versus 3.3.x)
Potential Impact Areas
- Payment Processing: Core functionality works consistently across all terminal models
- Scanner Operations: Scanner module detection and operation vary by model
- Terminal Management: Terminal identification and configuration
- Error Handling: New error code mapping for SDK 5.0
Schema Updates
- No database schema changes are required for this implementation
Example SQL
-- No SQL changes required
Rollback Information
Database rollback is not applicable for this implementation since no database changes were made.
If rollback is necessary, it would only require reverting code changes in the application through standard deployment processes without any database considerations.
Sunmi Terminal UI Optimization
Context: New Sunmi terminal models (P3, P3 Mix, and P2 Lite SE) required UI adaptations to accommodate different screen sizes and resolutions. The existing user interface was not optimized for these display formats, potentially causing display issues and degraded user experience.
Solution: Implemented comprehensive UI layout adaptations for all screen types across the new terminal models. Optimized text sizes, button dimensions, and element positioning to ensure proper display on the different screen formats while maintaining a consistent user experience.
Impact: Terminal users now experience properly formatted screens on all supported Sunmi models. The optimized UI ensures correct display of payment forms, transaction information, and system messages across all supported terminal devices with proper adaptation to each device's specific screen dimensions.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: None
- Code Changes: Modified layout XML files and dimension resources for UI components
- Filesystem Changes: Added new layout directories for P3 and P2 Lite SE screen resolutions
- Data Migration: None
Implementation Actions
- Created specialized layouts for P3 (720×1600) and P2 Lite SE (both FW 355×662 and HD 391×648 variants)
- Optimized text sizes, margins, and button dimensions for each display type
- Implemented percentage-based guidelines for responsive layouts on various screen sizes
- Adapted element positioning for both portrait and landscape orientations
- Updated icon and logo sizing for optimal display on each terminal model
- No Update Actions are required as all changes are implemented through standard code deployment
Configuration and Access Steps
- Access the terminal using appropriate Sunmi model (P3, P3 Mix, or P2 Lite SE)
- No special configuration required to activate the screen adaptations
- The system automatically detects terminal model and applies correct layout
- Navigation: Verify across all primary terminal screens (message, select, input forms)
Test Scenarios
-
Message Screen Display Verification
- Steps: Access various message screens (Approved, Declined, Error, etc.)
- Expected result: Text properly sized and centered, buttons correctly positioned at bottom of screen
-
Input Screen Keyboard Validation
- Steps: Access screens requiring numeric or text input
- Expected result: Keyboard appears properly sized and centered, with adequate spacing between keys
-
Selection Menu Display Check
- Steps: Access selection menus (Operation, Terminal ID, Settings, etc.)
- Expected result: Menu options display in properly sized rows with consistent spacing
-
Interface Display in Multiple Orientations
- Steps: Check screen rendering in both orientations (landscape and portrait), particularly for P3 Mix
- Expected result: UI elements adapt properly to orientation changes with correct alignment and sizing
-
Screen Adaptation Consistency
- Steps: Navigate through multiple screens on each terminal model
- Expected result: Consistent layout adaptation across all screens within the application
Common Issues
- Text truncation on longer message content
- Button alignment issues in landscape mode
- Keyboard layout spacing inconsistencies
- Image scaling in different screen resolutions
- Font rendering quality in certain resolutions
Potential Impact Areas
- UI Components: All terminal interface screens have been modified
- User Flow: No changes to transaction or operation flows
- Device Support: Adds proper support for P3, P3 Mix, and P2 Lite SE models while maintaining compatibility with existing devices
- Visual Experience: Improved visual consistency and readability across all terminal models
Schema Updates
- No database schema changes were required for this implementation
Example SQL
-- No SQL changes required
Rollback Information
No database changes were implemented, so no database rollback procedure is necessary.
The changes are UI-related only and can be reverted through standard application rollback procedures if needed.
Removed A-Z Button from Enter Transaction ID Screen
Context: On some terminal devices, tapping the 'A-Z' button on the "Enter Transaction ID" screen would open the native keyboard with no option to return back, causing navigation issues and preventing users from completing their transaction.
Solution: Removed the 'A-Z' button from the "Enter Transaction ID" screen since transaction IDs only accept numeric values, eliminating the problematic navigation path while maintaining all necessary input functionality.
Impact: Improved user experience with more intuitive keyboard controls that match the expected input type (numbers only), ensuring consistent interface across all terminal models and preventing users from encountering navigation dead-ends.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: None
- Filesystem Changes: None
- Data Migration: None
- Code Changes: Modified Java classes related to keyboard visibility control
Implementation Actions
- Removed the 'A-Z' button from the keyboard layout on the Transaction ID input screen
- Implemented consistent numeric-only keyboard across all terminal models
- No Update Actions are required as this is a purely UI-related change implemented through standard application deployment
Configuration and Access Steps
- Install and configure terminal application on both Sunmi and SoftPOS terminals
- Navigate to Void/Refund section in the application
- Verify the keyboard on the Enter Transaction ID screen no longer displays the A-Z button
- Navigation: Void/Refund → Enter Transaction ID
Test Scenarios
-
Transaction ID Input Keyboard Layout
- Steps: Navigate to Void/Refund section and observe the keyboard layout on the Enter Transaction ID screen
- Expected result: Keyboard should only display numeric keys without the A-Z button
-
Transaction ID Validation
- Steps: Enter numeric values in the transaction ID field and confirm the transaction
- Expected result: Numeric transaction IDs should be accepted without issues
-
Cross-Device Consistency
- Steps: Test the Enter Transaction ID screen on different terminal models (Sunmi, SoftPOS, P2 PRO, P2 mini, P3, P3 Mix, P2 Lite SE)
- Expected result: All devices should display consistent keyboard layout without the A-Z button
Common Issues
- Verify that removing the A-Z button doesn't affect any other keyboard screens in the application
- Ensure that transaction IDs with an asterisk prefix (*) still work correctly
- Check that keyboard works properly in both portrait and landscape orientations on tablet devices
Potential Impact Areas
- Transaction Processing: Minor UI improvement with no impact on transaction processing logic
- User Input: Simplified input with clearer indication that only numeric values are accepted
- Navigation Flow: Improved flow by removing a button that could lead to a dead-end state on some devices
Schema Updates
- No database schema changes were implemented as part of this task
Example SQL
-- No SQL changes required
Rollback Information
Database rollback is not applicable for this change since:
- No database modifications were made
- The change is isolated to UI component visibility
- The implementation only affects view logic in the application code
- No data structures or stored values are modified
If needed, the application code can be reverted to restore the previous behavior, but no database rollback would be necessary.
Optimized Receipt Display for Sunmi P3 Mix Terminals
Context: Sunmi P3 Mix terminals use a wider 80mm paper format compared to the standard 58mm width used by other terminals. The standard receipt template was not optimized for this wider format, causing misalignment and poor readability of transaction information.
Solution: Implemented dynamic receipt template formatting that automatically detects the Sunmi P3 Mix terminal model and adjusts the receipt layout accordingly. Modified the receipt elements including address display, line width, and spacing to properly utilize the wider paper format.
Impact: Merchants using Sunmi P3 Mix terminals now receive properly formatted receipts that make full use of the wider paper format. This improves receipt readability, professional appearance, and ensures all transaction information is properly aligned and displayed.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: None
- Code Changes: Updated receipt generation logic with dynamic width detection and formatting
- Filesystem Changes: None
- Data Migration: None
Implementation Actions
- Implemented terminal model detection for receipt template selection
- Created 80mm-specific receipt layout optimized for P3 Mix terminals
- Adjusted line spacing and element positioning for wider receipt format
- Modified address field display to utilize the additional horizontal space
- No Update Actions are required as changes are automatically applied when deployed
Configuration and Access Steps
- No special configuration is needed for testing
- Receipt testing requires a Sunmi P3 Mix terminal device with 80mm paper
- A test merchant account is required to process test transactions
- Navigation: Any transaction flow that generates a receipt
Test Scenarios
-
Standard Transaction Receipt Verification
- Steps: Process a standard payment transaction on a Sunmi P3 Mix terminal and generate a receipt
- Expected result: Receipt is properly formatted across the full 80mm width with correct alignment of all elements
-
Address Line Formatting Check
- Steps: Process a transaction with a merchant that has a long address
- Expected result: Address displays on a single line without wrapping, properly utilizing the wider format
-
Line Width Consistency Check
- Steps: Generate receipts for different transaction types (payment, refund, void)
- Expected result: All separator lines are consistently sized to the proper 80mm width
-
Model Detection Verification
- Steps: Print receipts on multiple terminal models (standard terminals and P3 Mix)
- Expected result: Only P3 Mix terminals should use the wider format; standard terminals should continue using the 58mm format
Common Issues
- Receipt may still use old formatting if terminal model is not properly detected
- Text spacing may appear inconsistent if receipt template is customized beyond standard settings
- Third-party receipt customizations may not be compatible with the new dynamic formatting
- Very long text fields may still require wrapping even with wider format
Potential Impact Areas
- Receipt Generation: Receipt formatting for all transaction types on Sunmi P3 Mix terminals
- Merchant Branding: Custom logo and header display on receipts
- Terminal Model Detection: Terminal model identification for feature activation
- Customer Experience: Improved receipt readability and professional appearance
Schema Updates
- No database schema changes were required for this enhancement
Example SQL
-- No SQL changes required for this implementation
Rollback Information
This change is fully rollback compatible as it only involves code changes to the receipt generation logic with no database modifications.
- Standard code rollback procedures can be applied if necessary
- No data migration or database restoration required for rollback
- Reverting to previous version would simply return to the standard receipt format
Optimized transaction response delivery on Sunmi terminals
Context: On Sunmi/SoftPOS terminals running version 5.2.5, transaction responses were only sent to the gateway after the user tapped the "Done" button on the confirmation screen, causing unnecessary delays in the payment process. This especially impacted merchants using the terminals in both managed and cloud modes.
Solution: Implemented a dual-approach solution to address the architectural constraints of Android. First, added Broadcast Receiver functionality to send immediate transaction notifications when the confirmation screen appears. Second, optimized the UI by removing the "Done" button for standard transactions and implementing automatic screen closing with appropriate timeouts.
Impact: Merchants experience significantly faster transaction processing with responses delivered immediately after processor approval. The streamlined UI automatically closes after displaying transaction results (1.5 seconds for standard transactions, 10 seconds for those requiring receipt printing or signature), eliminating unnecessary user interaction and improving transaction flow.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: None
- Code Changes: Modified transaction response logic and UI behavior in Sunmi/SoftPOS application
- Filesystem Changes: None
- Data Migration: None
Implementation Actions
- Implemented Broadcast Receiver functionality to send transaction results immediately when the approval screen appears
- Maintained standard API response delivery for backward compatibility with existing integrations
- Modified UI confirmation screens with the following improvements:
- Removed the "Done" button from approval screens without receipt/signature requirements
- Replaced the button area with the application logo for better visual appearance
- Implemented automatic screen timeout of 1.5 seconds for standard transactions
- Set 10-second timeout for transactions requiring receipt printing or signature
- Applied these UI improvements across all supported terminal models (P2 Lite SE, P2 Pro, P2 SMARTPAD, P3, P3 Mix, V3 Mix, and phone screens)
Configuration and Access Steps
- Install Sunmi/SoftPOS application version 5.2.6
- Ensure the test terminal is connected to the gateway
- Configure a test merchant account for transaction processing
- Navigation: Transaction Processing → Sale
Test Scenarios
-
Standard Sale Transaction Processing
- Steps: Initiate a sale transaction and tap/insert a payment card
- Expected result: Transaction response is sent to Gateway immediately after processor approval via Broadcast Receiver; confirmation screen displays without "Done" button and automatically closes after 1.5 seconds
-
Transaction with Receipt Printing
- Steps: Initiate a sale transaction with receipt printing enabled and tap/insert a payment card
- Expected result: Transaction response is sent immediately; confirmation screen displays with receipt options and automatically closes after 10 seconds
-
Transaction with Signature Requirement
- Steps: Initiate a transaction requiring signature and complete signature process
- Expected result: Transaction response is sent after signature completion; confirmation screen automatically closes after 10 seconds
-
Broadcast Receiver Verification
- Steps: Enable toast notifications in test mode and process a transaction
- Expected result: Both screenCode and responseCode notifications should appear, confirming that the Broadcast Receiver is functioning correctly
Common Issues
- Verify there are no delays in receiving transaction responses in the POS application
- Ensure the confirmation screen timeout works consistently across different terminal models
- Check for any unexpected behavior during fast consecutive transactions
- Verify that Broadcast Receiver messages are delivered consistently on all terminal models
Potential Impact Areas
- POS Integration: Applications expecting the previous response timing may need adjustments
- User Experience: Merchants and customers will notice faster transaction completions
- Transaction Processing: Monitor transaction reconciliation to ensure all transactions are properly recorded with the new flow
- Terminal Model Compatibility: Verify consistent behavior across all supported Sunmi terminal models
Schema Updates
- No database schema changes were required for this implementation
Example SQL
-- No SQL changes were required for this implementation
Rollback Information
No database changes were made, so no database rollback is required.
- This is a UI and business logic change only
- No impact on database structures or data