Modular 3DS Library

A plug-and-play Android library for 3D Secure (3DS) authentication that provides a unified API for different 3DS providers while maintaining EMVCo 3DS 2.x compliance.

Features

• Provider Abstraction: Unified API that works with any EMVCo-compliant 3DS library
• Plug-and-Play: Easy integration of new 3DS providers (Netcetera, Cardinal Commerce, etc.)
• Complete 3DS Flow: Handles authentication, challenge, and frictionless flows
• EMVCo 3DS 2.x Compliance: Full support for latest 3DS specifications
• Minification Safe: Works with aggressive R8/ProGuard optimization
• Mock Provider: Built-in mock provider for testing and development

Architecture

The library follows an SLF4J-inspired architecture with:

• Core API Layer: Unified interfaces and data models
• Provider Abstraction: Plugin system for different 3DS implementations
• Automatic Provider Detection: Runtime discovery of available providers
• Configuration Management: Type-safe configuration with builder pattern

Quick Start

1. Add Dependencies

dependencies {
    implementation 'io.hyperswitch:modular-3ds-api:1.0.0'
    
    // Choose your 3DS provider
    implementation 'io.hyperswitch:modular-3ds-netcetera:1.0.0'
    // OR
    // implementation 'io.hyperswitch:modular-3ds-cardinal:1.0.0'
}

2. Initialize the Library

val configuration = ThreeDSConfiguration.Builder()
    .setEnvironment(ThreeDSEnvironment.SANDBOX)
    .setDirectoryServerId("your-ds-id")
    .setTimeout(30000)
    .build()

ThreeDSManager.getInstance().initialize(this, configuration, object : InitializationCallback {
    override fun onInitializationSuccess() {
        // Ready to authenticate
    }
    
    override fun onInitializationFailure(error: ThreeDSError) {
        // Handle initialization error
    }
})

3. Perform Authentication

val request = AuthenticationRequest(
    transactionId = "txn-123",
    amount = "100.00",
    currency = "USD",
    cardNumber = "4000000000000000",
    expiryMonth = "12",
    expiryYear = "25",
    merchantName = "Your Merchant",
    merchantCategoryCode = "5411",
    acquirerBin = "123456",
    acquirerMerchantId = "merchant-123",
    // ... other fields
)

ThreeDSManager.getInstance().authenticate(request, object : AuthenticationCallback {
    override fun onAuthenticationSuccess(response: AuthenticationResponse) {
        // Handle successful authentication
        val liabilityShift = response.liabilityShift
        val authValue = response.authenticationValue
    }
    
    override fun onAuthenticationFailure(error: ThreeDSError) {
        // Handle authentication failure
    }
    
    override fun onChallengeRequired() {
        // Challenge UI will be presented automatically
    }
    
    override fun onAuthenticationCancelled() {
        // User cancelled the authentication
    }
})

Provider Support

Available Providers

• Mock Provider: Built-in provider for testing (always available)
• Netcetera Provider: Integration with Netcetera 3DS SDK (coming soon)
• Cardinal Commerce Provider: Integration with Cardinal Commerce SDK (coming soon)

Provider Detection

The library automatically detects available providers at runtime:

// Check available providers
val providers = ThreeDSManager.getAvailableProviders()
val providerInfo = ThreeDSManager.getProviderInfo()

// Get current provider
val currentProvider = ThreeDSManager.getInstance().getCurrentProvider()

Testing

The library includes a mock provider for testing different 3DS scenarios:

// Register mock provider (for testing)
ProviderRegistry.registerProvider(MockProviderFactory())

// Test different scenarios based on card numbers:
// - Cards ending in 0000: Frictionless success
// - Cards ending in 1111: Challenge required
// - Cards ending in 9999: Authentication failure
// - Other cards: Authentication attempted

Configuration Options

val configuration = ThreeDSConfiguration.Builder()
    .setEnvironment(ThreeDSEnvironment.PRODUCTION) // or SANDBOX
    .setDirectoryServerId("your-directory-server-id")
    .setTimeout(30000) // 30 seconds
    .setPreferredProvider("netcetera") // Optional
    .setEnableLogging(true) // For debugging
    .setUiCustomization(uiCustomization) // Optional UI customization
    .build()

EMVCo Compliance

The library supports all EMVCo 3DS 2.x features:

• Authentication Status: Y, N, A, U, R, C
• Challenge Flow: Full challenge UI support
• Device Data Collection: Risk assessment data
• UI Customization: Merchant branding support
• Message Versions: 2.2.0 and backwards compatibility

ProGuard/R8 Support

The library is fully compatible with code minification. Consumer ProGuard rules are automatically applied.

Sample App

Check the app module for a complete integration example demonstrating:

• Provider detection and selection
• 3DS initialization
• Authentication flows
• Error handling
• UI integration

License

[Add your license here]

Contributing

[Add contribution guidelines here]