# ๐ŸŒ International Credit Request (ReqPay) Implementation ## Overview This document outlines the implementation of the International Credit Request (ReqPay) API as per NPCI UPI 2.0 specification. The implementation handles the complete international UPI transaction flow with enhanced merchant details, risk scoring, device fingerprinting, and FX conversion. ## ๐Ÿ“Œ Key Features Implemented ### 1. Enhanced XML Parsing (`UpiXmlSchema.parse_req_pay/1`) - **Namespace Support**: Handles `xmlns:upi="http://npci.org/upi/schema/"` - **Complete Field Extraction**: Parses all 50+ fields from the international ReqPay structure - **Device Information**: Extracts mobile, IP, geocode, location, OS, app details - **Merchant Details**: Parses MID, SID, TID, merchant type, onboarding info - **FX Splits**: Handles baseAmount, baseCurr, FX rate, markup - **Risk Scores**: Extracts SP and NPCI risk scores ### 2. Advanced Validation (`validate_international_req_pay_fields/1`) - **Purpose Code**: Enforces `purpose="11"` for international merchant credits - **Transaction Type**: Validates `CREDIT` or `REVERSAL` types - **Expiry Rules**: Validates EXPIREAFTER between 1-64800 minutes - **Risk Scores**: Validates scores are 0-100 range - **Merchant ID**: Validates MID format (6-15 alphanumeric) - **Currency**: Enforces INR for settlement currency ### 3. International Payment Processing (`UpiTransactionManager.process_international_payment_request/1`) - **Risk Assessment**: Checks SP and NPCI risk scores against thresholds - **FX Conversion**: Performs currency conversion with markup calculation - **Merchant Validation**: Validates merchant details against registry - **Device Fingerprinting**: Processes device info for fraud detection - **Partner Integration**: Sends enhanced payload to partner systems - **Settlement Details**: Handles approval numbers and settlement amounts ### 4. Enhanced Error Handling - **Risk Threshold Exceeded**: Error code `16` - **FX Conversion Failed**: Error code `14` - **Merchant Not Found**: Error code `ZR` - **Validation Errors**: Error code `93` - **XML Format Errors**: Error code `ZH` ## ๐Ÿ—๏ธ XML Structure Support ### Request (ReqPay) ```xml ``` ### Response (RespPay) ```xml ``` ## ๐Ÿ”„ Processing Flow 1. **XML Reception**: Controller receives international ReqPay XML 2. **Detection**: `is_international_payment?/1` detects international indicators 3. **Parsing**: `extract_international_req_pay_data/1` parses all fields 4. **Validation**: `validate_international_payment_data/1` validates business rules 5. **Risk Assessment**: Check SP/NPCI risk scores against thresholds 6. **FX Conversion**: Convert base currency to INR using provided rates 7. **Partner Processing**: Send enhanced payload to partner system 8. **Response Generation**: Create RespPay with settlement details ## ๐ŸŽฏ International Payment Indicators The system detects international payments by checking for: - UPI namespace: `xmlns:upi="http://npci.org/upi/schema/"` - Product type: `prodType="UPI_INTL"` - Purpose code: `purpose="11"` - Merchant structure: `` element - Risk scores: `` element - Device info: `` element - FX splits: `` **Detection Logic**: Considers international if โ‰ฅ2 indicators present. ## ๐Ÿ›ก๏ธ Risk Management ### Risk Score Validation - **SP Risk Score**: Service Provider risk assessment (0-100) - **NPCI Risk Score**: NPCI network risk assessment (0-100) - **Threshold**: Transactions with scores >80 are rejected - **Error Code**: `16` (Risk threshold exceeded) ### Device Fingerprinting Captures comprehensive device information: - Mobile number, IP address, geocode - Device type, ID, OS, app version - Location data, capabilities - Used for fraud detection and compliance ## ๐Ÿ’ฑ FX Handling ### Currency Conversion - **Base Amount**: Original foreign currency amount - **Base Currency**: Foreign currency code (SGD, USD, etc.) - **FX Rate**: Conversion rate to INR - **Markup**: PSP markup percentage - **Settlement**: Final INR amount = baseAmount ร— FX ร— (1 + markup/100) ### Validation - Settlement currency must be `INR` - FX rate must be positive number - Markup percentage validated - Conversion amounts logged for audit ## ๐Ÿช Merchant Validation ### Required Fields - **MID**: Merchant ID (6-15 alphanumeric) - **Legal Name**: Registered business name - **Brand Name**: Display name - **Merchant Type**: SMALL, MEDIUM, LARGE - **Onboarding Type**: DIRECT, AGGREGATOR - **Account Details**: IFSC, account number, type ### Validation Rules - MID format: `^[A-Za-z0-9]{6,15}$` - Merchant must exist in registry - Account details must be valid - Onboarding status must be active ## ๐Ÿ“Š Error Codes & Handling | Code | Description | Scenario | |------|-------------|----------| | `00` | Success | Transaction completed | | `01` | Pending | Timeout escalation started | | `02` | Failed | General transaction failure | | `10` | Debit Failed | Insufficient funds | | `14` | External Error | Partner/FX system error | | `16` | Risk Threshold | Risk score >80 | | `93` | Validation Error | Business rule violation | | `ZH` | Invalid XML | XML parsing failure | | `ZR` | Merchant Not Found | Invalid merchant | ## ๐Ÿ”ง Configuration ### Timeouts - **Default Expiry**: 30 minutes - **Maximum Expiry**: 64800 minutes (45 days) - **Minimum Expiry**: 1 minute ### Risk Thresholds - **SP Risk**: Max 80 - **NPCI Risk**: Max 80 - **Combined**: Either score >80 triggers rejection ### FX Settings - **Base Currencies**: SGD, USD, AED, EUR, GBP - **Settlement Currency**: INR only - **Markup Range**: 0-10% typically ## ๐Ÿงช Testing Run the test script to validate implementation: ```bash elixir test_international_reqpay.exs ``` Tests cover: - XML parsing accuracy - Validation logic - Error handling - Response generation - Edge cases ## ๐Ÿ“‹ Compliance Notes ### NPCI Requirements - โœ… UPI 2.0 namespace support - โœ… International purpose code (11) - โœ… Enhanced merchant onboarding data - โœ… Risk scoring integration - โœ… Device fingerprinting - โœ… FX transparency with splits ### Audit Trail All transactions logged with: - Original and converted amounts - FX rates and markup applied - Risk scores and decisions - Device fingerprint data - Approval numbers for reconciliation ## ๐Ÿš€ Deployment Checklist - [ ] UpiXmlSchema functions deployed - [ ] UpiTransactionManager updated - [ ] Controller routing configured - [ ] Partner API integration tested - [ ] Risk threshold configuration verified - [ ] FX rate feeds connected - [ ] Error monitoring setup - [ ] Audit logging enabled --- **Implementation Status**: โœ… Complete **Compliance**: โœ… NPCI UPI 2.0 International **Testing**: โœ… Unit tests included **Documentation**: โœ… Comprehensive