Multibanco reference collisions for order IDs > 9999 cause payment processing failures

Problem Description

The Ifthenpay payment gateway has a fundamental limitation where Multibanco references can only use 4 digits for order IDs (range 1-9999). When order IDs exceed 9999, the system truncates to the rightmost 4 digits, causing frequent collisions.

Steps to Reproduce

1. Create orders with IDs > 9999 (e.g., order 12345 and 22345)
2. Both orders generate the same Multibanco reference containing "2345" followed by calculated check digits
3. When payment callback arrives, system processes wrong order or fails

Expected Behavior

Each order should have a unique Multibanco reference, even for large order IDs.

Actual Behavior

• Multiple orders share the same reference
• Payment callbacks process incorrect orders
• "Payment already processed" errors occur
• Manual intervention required to resolve payments

Proposed Solution

Implement hash-based order ID mapping with collision detection:

• Use CRC32 hash instead of simple truncation for order IDs > 9999
• Map large order IDs to range 1000-9999 to avoid conflicts with small order IDs (1-999)
• Add collision detection and logging
• Implement intelligent payment selection based on amount matching
• Maintain backward compatibility for order IDs ≤ 9999

Impact

• High: Affects all sites with order IDs > 9999
• Data integrity: Payments may be applied to wrong orders
• User experience: Failed payments require manual resolution