Release V9.2.7.1
Financial Reporting Improvements
Enhanced financial reporting capabilities with improved statement generation:
Reseller Statement Improvements
Context: The previous Reseller Statement logic had limitations in handling various fee types and lacked support for multiple resellers per merchant, causing inefficiencies in financial reporting and reconciliation processes.
Solution: Implemented a new Reseller Statement generation system with enhanced breakdown reporting, support for two resellers per merchant (primary and agent), improved fee handling, and more flexible export options.
Impact: Users can now generate more detailed Reseller Statements, access data in JSON/CSV formats, properly account for Buy Rate fees, utilize remittance hold functionality, and manage two different resellers (primary and agent) per merchant.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: Added new tables (ResellerStatementExtended, ResellerStatementExtendedDetail, ResellerStatementExtendedBreakdown) and fields to existing tables (Reseller, Merchant, MerchantProcessingStatistics, RemittanceTransaction)
- Configuration Changes: Added new system settings (unipay.business.reseller-statement-day, unipay.business.reseller-statement-generation-day) and new classifications
- Code Changes: Implemented new business logic for statement generation, fee calculation, and dual reseller support
- Filesystem Changes: Added new notification template for reseller-statement-processed
- Data Migration Needs: No data migration needed as this is a new feature that runs in parallel with existing functionality
Implementation Actions
- Deploy database schema changes through standard delta scripts
- Configure new system settings with appropriate values
- Set up classifier values for new business logic support
- Test statement generation with the new system
Configuration and Access Steps
- Ensure the following properties are properly configured: unipay.business.reseller-statement-day, unipay.business.reseller-statement-generation-day
- Configure a reseller with proper commission rates and platform fees
- Optionally configure an agent on a merchant using the agentCode field
- Set the buyRateHandlingMode field on the reseller to either 'E' (Processing Expense) or 'F' (Reseller Fee)
- Navigation: Reseller P./Remittance/Statements*/Reseller Statement List
Test Scenarios
-
Generate New Reseller Statement
- Steps: Generate new statements via the job scheduler; verify ResellerStatementExtended and ResellerStatementExtendedDetail tables contain the correct data; confirm all fee types are properly calculated and included in the statement
- Expected result: Statements are correctly generated with all relevant fees and data
-
Test Remittance Hold Functionality
- Steps: Set isRemittanceHoldEnabled to true on a reseller; generate a statement and verify it receives an 'A' (Adjustment) record with 'Remittance Hold' description; verify the balance field is updated correctly; test automatic hold on failed remittance transactions
- Expected result: Remittance holds are applied correctly with proper balance tracking
-
Test Dual Reseller Configuration
- Steps: Configure a merchant with both a primary reseller and an agent; process transactions and generate statements; verify both resellers receive appropriate statements with correct commission calculations
- Expected result: Both primary reseller and agent receive statements with correctly split commissions
Common Issues
- Missing breakdown data if resellerStatementExtendedFk is not properly set in ResellerStatementExtendedBreakdown
- Incorrect fees calculation if ProcessingCostCl or buyRateHandlingMode fields are not set properly
- Permissions issues if user access logic for agent relationships is not working
- Missing email notifications if remittanceEmailRecipientList is not configured
Potential Impact Areas
- Financial Reporting: Statement generation, fee calculations, and financial reconciliation
- User Interface: New statement format, breakdown displays, and export options
- Remittance Processing: Remittance hold functionality and balance tracking
- Data Export: New JSON and CSV export formats for statement data
Schema Updates
- Added new tables: ResellerStatementExtended, ResellerStatementExtendedDetail, ResellerStatementExtendedBreakdown
- Added new fields to Reseller table: isRemittanceHoldEnabled, balance, remittanceHoldNote, remittanceHoldUserName, platformFeesRate, buyRateHandlingMode
- Added new field to Merchant table: agentCode
- Added new fields to MerchantProcessingStatistics: ProcessingCostCl, buyRateHandlingMode, agentCode, resellerPlatformFeeRate, agentPlatformFeeRate
- Added new fields to RemittanceTransaction: resellerCode, resellerStatementExtendedFk
- Added indexes: reseller_statement_extended_reseller_code_idx, statement_code_index
Example SQL
ALTER TABLE reseller ADD COLUMN is_remittance_hold_enabled BOOLEAN DEFAULT false;
ALTER TABLE reseller ADD COLUMN balance DECIMAL(19,6) DEFAULT 0;
ALTER TABLE merchant ADD COLUMN agent_code VARCHAR(64);
CREATE TABLE reseller_statement_extended (
id BIGSERIAL PRIMARY KEY,
reseller_code VARCHAR(64) NOT NULL,
...
);
Rollback Information
Database rollback for this feature is not possible due to data loss operations, complex transformations, cascading changes, and production data dependencies.
Once financial transactions are created based on the new statements, they cannot be reversed without affecting financial reconciliation. External systems may consume the exported data, creating external dependencies.
Alternative Recovery Strategy: If problems occur, implement forward fixes while maintaining the new schema. The dual-system design (supporting both old and new statement formats) provides a fallback mechanism without requiring database schema rollback.
Important: Schedule deployment during non-business hours in the client's time zone as potential offline periods may extend beyond estimates due to unforeseen circumstances.
Bug Fixes
Notable fixes in this release:
- Fixed Holder Name Processing with URL Encoded Characters(UP-976)
- Fix for Transaction Duplication in ACH Files(UP-998)
Fixed Holder Name Processing with URL Encoded Characters
Context: When processing payments with a "+" character in the holderName field (commonly used between first and last names in URL encoding), the system was removing the "+" character without replacing it with a space, causing merged names to be sent to processors.
Solution: Modified the validation logic to replace "+" characters with spaces in the holderName field, ensuring proper name formatting when data is sent to payment processors.
Impact: Transactions with URL-encoded name format (using "+" between first and last names) will now be properly processed, reducing payment declines caused by incorrect name formatting.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: None
- Code Changes: Modified validation logic for holderName field processing
- Filesystem Changes: None
- Data Migration Needs: None
Implementation Actions
- Deploy code changes through standard deployment
- No additional configuration or setup required
- No database schema modifications needed
- No data migration required
Configuration and Access Steps
- Access to API testing environment is required
- Valid payment credentials for testing transactions
- Navigation: API endpoint testing tools (Postman or equivalent)
Test Scenarios
-
Test API transaction with "+" in holderName
- Steps: Send a transaction request with holderName="FIRST+LAST"
- Expected result: The processor receives "FIRST LAST" with proper space
-
Verify space conversion in database records
- Steps: Check database entries for transactions with holderName containing "+"
- Expected result: The transaction should store the name with proper spacing
-
Test other special characters in holderName
- Steps: Send transactions with holderName containing hyphens, apostrophes, etc.
- Expected result: These characters should be preserved according to existing validation rules
Common Issues
- Ensure proper URL encoding is used when sending API requests
- Verify the holderName field in response correctly shows the converted value
- Check related transaction logs to confirm the processor received properly formatted data
Potential Impact Areas
- Payment Processing: API transactions with special characters in holderName
- Transaction Reports: Display of cardholder names in transaction reports
- Data Storage: Format of stored cardholder names in the database
Schema Updates
- No database schema changes were implemented
- No data modifications were performed
- The fix only modifies application logic for processing input data
Rollback Information
Rollback is possible as the change does not affect database structures or persistent data. If needed, reverting to the previous code version would restore the original validation behavior without requiring data manipulation.
Fix for Transaction Duplication in ACH Files
Context: When a transaction contained multiple charge items, the system incorrectly created duplicate records in ACH files, resulting in multiple identical charges in bank settlement files.
Solution: Modified the database query logic to ensure each transaction is processed only once, regardless of how many charge items it contains.
Impact: ACH files now correctly contain a single record per transaction, preventing duplicate charges and bank returns.
- Implementation Details
- Testing & Validation
- Database Changes
System Changes Overview
- Database Changes: None
- Configuration Changes: None
- Code Changes: Modified query logic for ACH file generation
- Filesystem Changes: None
- Data Migration Needs: None
Implementation Actions
- Deploy code changes through standard deployment
- No additional configuration required
- No data migration needed
- No manual intervention required during update
Configuration and Access Steps
- No configuration changes are required for this fix
- Testing requires access to the ACH file generation process
- Navigation: Processing → ACH Processing → Generate ACH File
Test Scenarios
-
Transaction with Multiple Items
- Steps: Create a transaction with 5 charge items (e.g., 5 items of $36 each for a total of $180); process the transaction through ACH processing; verify the generated ACH file contains only one record for this transaction with the correct total amount
- Expected result: Only one record appears in the ACH file with the total amount of $180
-
Multiple Transactions with Items
- Steps: Create several transactions, each with different numbers of charge items; process these transactions in a batch through ACH processing; verify each transaction appears only once in the generated ACH file
- Expected result: Each transaction appears exactly once with its correct total amount
-
Mixed Transaction Types
- Steps: Process a batch containing both transactions with items and regular transactions; generate ACH file for all transactions; verify all transactions appear correctly without duplication
- Expected result: All transactions appear exactly once with correct amounts
Common Issues
- Incorrect file format may cause parsing issues when examining ACH files
- Check ACH file directly rather than relying on UI representations
- Verify transaction amounts match across payment system and ACH file
Potential Impact Areas
- Payment Processing: The fix affects how transactions are processed in ACH files
- Settlement: Ensures correct settlement amounts for transactions with multiple items
- Reporting: May affect reconciliation between system and bank records
Schema Updates
- No database schema changes were implemented
- No data modifications were performed
- The fix only modifies the query that selects transaction data from existing tables
Rollback Information
Rollback is possible for this implementation as it involves only code changes. The changes don't affect database structure or perform any data transformations. If issues arise after deployment, reverting to the previous code version would fully roll back the changes without any database impact.
- Backup of the previous code version
- Scheduled deployment window for application restart
- Testing to verify system behavior after rollback