Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

This PR introduces a major enhancement to the HyperSwitch payment processing system with the implementation of Unified Connector Service (UCS) Pre-Authentication Integration, fundamentally improving how authentication flows are handled across different payment connectors.

UCS Pre-Authentication Integration

The core of this PR is the implementation of a sophisticated pre-authentication system that integrates with the Unified Connector Service to provide enhanced 3D Secure (3DS) handling and authentication flows. This implementation addresses the growing complexity of payment authentication requirements across different connectors and provides a unified approach to handling pre-authentication challenges.

Key Components:

1. Pre-Authentication Flow Architecture

• UCS Pre-Authentication Call: During the authorize flow, the system now intelligently determines when to call UCS pre-authentication based on connector capabilities and payment method requirements
• Flow Decision Logic: Implemented sophisticated logic to decide between standard authorization, pre-authentication, or alternate flows based on:
  • Connector specifications and capabilities
  • Payment method type (cards, digital wallets, etc.)
  • 3DS requirements and authentication challenges
  • Merchant configuration and risk parameters

2. Enhanced Authentication Handling

• 3DS Flow Management: The system now properly manages complex 3DS flows including frictionless, challenge, and step-up authentication scenarios
• Pre-Authentication Response Processing: Comprehensive handling of UCS pre-authentication responses, including:
  • Challenge redirects and user interaction flows
  • Authentication result validation and verification
  • Error handling and fallback mechanisms
  • Session management and state preservation

3. Connector Integration Framework

• Unified Authentication Interface: Created a standardized interface for connectors to participate in pre-authentication flows
• Connector-Specific Logic: Implemented connector-specific pre-authentication handling for complex scenarios, particularly for connectors like Cybersource that require sophisticated flow management

Technical Implementation:

Core Files Modified:

• crates/router/src/core/payments/flows/authorize_flow.rs: Main authorization flow with UCS pre-authentication integration
• crates/router/src/core/unified_connector_service.rs: UCS service integration and pre-authentication handling
• crates/external_services/src/grpc_client/unified_connector_service.rs: gRPC client for UCS communication
• crates/hyperswitch_interfaces/src/unified_connector_service/transformers.rs: Data transformation for UCS requests/responses

Additional Changes

• This PR modifies the API contract
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Motivation and Context

This change is required to address the growing complexity and fragmentation in payment authentication across different connectors. The current payment landscape presents several critical challenges:

Authentication Complexity Explosion:

• Payment connectors have widely varying authentication requirements and 3DS implementations
• Each connector implements authentication flows differently, leading to code duplication and maintenance overhead
• Complex scenarios like step-up authentication, challenge flows, and frictionless authentication are handled inconsistently

Regulatory Compliance Pressure:

• PSD2 and other regulations require strong customer authentication (SCA) for many transactions
• Different regions have varying authentication requirements that must be handled correctly
• Failure to properly implement authentication flows can result in transaction failures and compliance issues

User Experience Challenges:

• Inconsistent authentication experiences across different payment methods and connectors
• Poor handling of authentication challenges leads to user friction and cart abandonment
• Lack of intelligent flow routing results in unnecessary authentication steps

Technical Debt and Scalability:

• Existing authentication logic is scattered across multiple connectors with no unified approach
• Adding new connectors with complex authentication requirements is difficult and error-prone
• No standardized framework for handling emerging authentication methods and standards

The UCS Pre-Authentication Integration solves these problems by:

1. Unified Authentication Framework: Provides a single, standardized approach to handling authentication across all connectors
2. Intelligent Flow Decision Making: Dynamically determines the optimal authentication flow based on real-time context
3. Enhanced 3DS Handling: Properly manages complex 3DS scenarios including frictionless, challenge, and step-up flows
4. Future-Proof Architecture: Designed to accommodate emerging authentication methods and regulatory requirements
5. Improved User Experience: Smoother authentication flows with intelligent challenge management and reduced friction

This implementation represents a fundamental shift from connector-specific authentication handling to a unified, intelligent system that can adapt to the evolving payment authentication landscape while maintaining backward compatibility and providing a foundation for future enhancements.

How did you test it?

Cannot be tested end to end yet. Since Authenticate, PostAuthenticate and Authorize changes are pending

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible