3DS transactions

Integrate 3D Secure (3DS) into your checkout.

Overview

By implementing 3DS authentication into your payment flow, you benefit from:

Additional security: 3DS adds multiple layers of authentication and risk assessment
Liability shift: Successful 3DS authentication typically shifts fraud liability from merchant to card issuer
Higher success rate: Banks are more likely to approve 3DS-authenticated transactions

However, the 3DS payment flow is longer than the non-3DS one due to the additional authentication steps. It may also require active customer participation if a challenge is presented.

Payment flow

The 3D Secure flow is made up of nine key steps.

Step 1: Submission

The customer taps the submit button or the payment is triggered programmatically. The submit() method in CardSubmitComponent is invoked and validation occurs inside it. If validation passes, the method continues with the payment processing. If it fails, the method exits early and doesn't proceed with the transaction.

Step 2: Card tokenisation

If it's a new card, the SDK sends the card details to the tokenisation service. If it's a saved card, the SDK retrieves the existing token.

Step 3: Evaluation

The SDK evaluates whether 3DS authentication is required. In this flow, 3DS is required based on factors like transaction amount, risk assessment, or regulatory requirements.

Step 4: Pre-initiation

This is the initial step in the 3DS authentication flow. It establishes the authentication session by sending transaction and card details to the payment processor.

This step has two associated callbacks:

onPreInitiateAuthentication: () -> PreInitiateIntegratedAuthenticationData?
- Purpose: Returns configuration for the authentication setup.
- Return: PreInitiateIntegratedAuthenticationData containing acquirer profile, provider ID, timeout, and authentication indicators.
- Return null: To skip 3DS authentication (e.g., for low-risk transactions).
onPostInitiateAuthentication: (AuthenticationResult) -> Unit
- Purpose: Receives the result of the pre-initiation call.
- Parameter: AuthenticationResult (either PreInitiateSuccessAuthenticationResult or FailedAuthenticationResult).
- Contains: Authentication ID, state, SCA mandate status, applicable exemptions.

Step 5: Fingerprinting

During this step, device information and browser characteristics are collected by the fingerprinting component. It creates a hidden iframe that submits transaction details to the issuer's fingerprint URL, enabling risk assessment based on the user's device profile.

Step 6: Authentication

The 3DS server evaluates the transaction risk and determines the authentication path:

Frictionless flow: If the transaction is low-risk, authentication completes automatically without customer interaction.
Challenge flow: If additional verification is needed, the customer completes the 3DS authentication challenge (PIN entry, SMS code, biometric verification, etc.)

The authentication step has two associated callbacks:

onPreAuthentication: (PreInitiateSuccessAuthenticationResult) -> InitiateIntegratedAuthenticationData?
- Purpose: Configures the main authentication parameters.
- Parameter: PreInitiateSuccessAuthenticationResult containing pre-initiation results.
- Return: InitiateIntegratedAuthenticationData with challenge window size, timeout, callback URL.
- Return null: To abort the authentication process.
onPostAuthentication: (AuthenticationResult, ThreeDSAuthenticationData?) -> Unit
- Purpose: Receives authentication results and challenge data.
- Parameter 1: AuthenticationResult indicating success/failure status.
- Parameter 2: ThreeDSAuthenticationData? containing CAVV, ECI, authentication ID, XID, and other 3DS data
- Contains: Complete authentication results for transaction processing.

Step 7: Authentication result

The SDK receives the 3DS authentication result indicating whether authentication was successful, failed, or requires additional action.

Step 8: Authorisation

This is the final step of the 3DS authentication flow. You receive the transaction data along with the 3DS authentication results and decide whether to proceed. At this point, you can still add additional data or cancel the transaction entirely. The SDK then sends the authorisation request to the payment gateway, including the 3DS authentication data.

The authorisation step has two associated callbacks:

onPreAuthorisation: (PreAuthorisationData) -> TransactionInitiationData?
- Purpose: Provides final transaction data, including 3DS authentication results. This is your last chance to modify the transaction before authorisation.
- Parameter: PreAuthorisationData containing authentication results, transaction details, and 3DS data.
- Return: TransactionInitiationData with SCA exemption data, additional transaction parameters.
- Return null: To proceed with default authorisation settings.
onPostAuthorisation: (SubmitResult) -> Unit
- Purpose: Receives the final transaction result from the payment gateway.
- Parameter: SubmitResult (one of AuthorisedSubmitResult, CapturedSubmitResult, RefusedSubmitResult, FailedSubmitResult).
- Contains: Final transaction status, provider response, authentication confirmation, transaction reference.
- Usage: Handle payment success/failure, navigate to appropriate screens, update UI state.

Step 9: Authorisation result

You receive the final authorisation response from the payment gateway. The transaction is either approved or declined and final transaction details are available, along with 3DS authentication confirmation.

Additional 3DS callbacks

Beyond the core flow callbacks, the SDK provides additional callbacks for monitoring specific 3DS events:

Authentication status callbacks

onAuthenticationStarted: () -> Unit
- Purpose: Called when 3DS authentication begins.
- Usage: Show loading indicators, update UI state.
onAuthenticationCompleted: () -> Unit
- Purpose: Called when 3DS authentication ends (success or failure).
- Usage: Hide loading indicators, reset UI state.
onAuthenticationSuccess: (ThreeDSAuthenticationData) -> Unit
- Purpose: Called specifically for successful authentication.
- Parameter: Complete ThreeDSAuthenticationData with all 3DS fields.
- Usage: Log successful authentication, track analytics.
onAuthenticationFailure: (String, String?) -> Unit
- Purpose: Called specifically for failed authentication.
- Parameter 1: Error message describing the failure.
- Parameter 2: Optional error code for categorising failures.
- Usage: Handle authentication errors, display appropriate user messages.

Challenge flow callbacks

onChallengeStarted: () -> Unit
- Purpose: Called when a 3DS challenge begins.
- Usage: Prepare UI for challenge presentation.
onChallengeCompleted: (Boolean) -> Unit
- Purpose: Called when a 3DS challenge ends.
- Parameter: Boolean indicating whether challenge was successful.
- Usage: Handle challenge results, update payment flow state.

Implementation

Before you start

To use 3D Secure in your application, you first need to enable it in the Unity Portal:

In the Unity Portal, go to Merchant setup > Merchant groups.
Select a merchant group.
Click the Services tab.
Click Edit in the Card service row.
Click Configure modules in the top right.
Click the toggle next to ThreeD secure service.

You'll also need to get the following from your payment processor:

acquirerProfileId: Your acquirer profile identifier.
providerId: Your 3DS provider identifier.
Test credentials for the sandbox environment.

Step 1: Configure your SDK

To start, set up your PxpSdkConfig to include the shopper object.

val sdkConfig = PxpSdkConfig(
    environment = Environment.TEST,
    session = SessionConfig(
        sessionId = "your_session_id",
        sessionData = "your_session_data"
    ),
    transactionData = TransactionData(
        amount = 99.99,
        currency = CurrencyType.USD,
        entryType = EntryType.ECOM,
        intent = IntentType.AUTHORISATION,
        merchantTransactionId = "order-123",
        merchantTransactionDate = { Instant.now().toString() },
        // Include 3DS-friendly data
        shopper = Shopper(
            email = "customer@example.com",
            firstName = "John",
            lastName = "Doe"
        )
    ),
    clientId = "your_client_id",
    ownerId = "Unity",
    ownerType = "MerchantGroup",
    merchantShopperId = "shopper-123"
)

Step 2: Implement callbacks

Next, implement your chosen callbacks. Note that some are required.

val cardSubmitConfig = CardSubmitComponentConfig(
    // REQUIRED: Provide 3DS configuration
    onPreInitiateAuthentication = {
        PreInitiateIntegratedAuthenticationData(
            acquirerProfileId = "your_acquirer_profile_id",
            providerId = "your_3ds_provider_id",
            requestorAuthenticationIndicator = RequestorAuthenticationIndicatorType.PAYMENT_TRANSACTION,
            timeout = 120
        )
    },

    // OPTIONAL: Handle the pre-initiation result
    onPostInitiateAuthentication = { result ->
        Log.d("3DS", "3DS pre-initiation completed: $result")
        when (result) {
            is PreInitiateSuccessAuthenticationResult -> {
                Log.d("3DS", "3DS setup successful")
            }
            is FailedAuthenticationResult -> {
                Log.e("3DS", "3DS setup failed: ${result.errorReason}")
            }
        }
    },
    
    // REQUIRED: Configure main authentication
    onPreAuthentication = { preInitResult ->
        Log.d("3DS", "Configuring 3DS authentication: $preInitResult")
        
        InitiateIntegratedAuthenticationData(
            merchantCountryNumericCode = "840",
            merchantLegalName = "Your company name",
            challengeWindowSize = "04",
            requestorChallengeIndicator = "01",
            challengeCallbackUrl = "https://your-domain.com/3ds-callback",
            timeout = 300
        )
    },

    // OPTIONAL: Handle the authentication result
    onPostAuthentication = { authResult, threeDSData ->
        Log.d("3DS", "3DS authentication completed: $authResult")
        Log.d("3DS", "3DS data: $threeDSData")
        
        when (authResult) {
            is InitiateIntegratedSuccessAuthenticationResult -> {
                Log.d("3DS", "Authentication successful")
            }
            is FailedAuthenticationResult -> {
                Log.e("3DS", "Authentication failed or challenged")
            }
        }
    },
    
    // REQUIRED: Final transaction approval
    onPreAuthorisation = { preAuthData, error ->
        Log.d("3DS", "Pre-authorisation data: $preAuthData")
        if (error != null) {
            Log.e("3DS", "Pre-authorisation error: ${error.message}")
        }
        
        // Return transaction initiation data
        preAuthData.transactionInitiationData
    },

    // OPTIONAL: Handle the final result
    onPostAuthorisation = { result ->
        when (result) {
            is AuthorizedSubmitResult -> {
                Log.d("3DS", "Payment successful with 3DS!")
                Log.d("3DS", "Provider response: ${result.providerResponse.message}")
                // Navigate to success screen
                navigateToSuccessScreen()
            }
            is CapturedSubmitResult -> {
                Log.d("3DS", "Payment captured with 3DS!")
                Log.d("3DS", "Provider response: ${result.providerResponse.message}")
                navigateToSuccessScreen()
            }
            is RefusedSubmitResult -> {
                Log.e("3DS", "Payment refused: ${result.stateData.message}")
                showError("Payment was declined: ${result.stateData.message}")
            }
            is FailedSubmitResult -> {
                Log.e("3DS", "Payment failed: ${result.errorReason}")
                showError("Payment failed: ${result.errorReason}")
            }
            else -> {
                Log.e("3DS", "Unknown result type: ${result::class.simpleName}")
                showError("Payment completed with unknown status")
            }
        }
    }
)

val cardSubmitComponent = pxpCheckout.createComponent<CardSubmitComponent, CardSubmitComponentConfig>(
    ComponentType.CARD_SUBMIT,
    cardSubmitConfig
)

Step 3: Handle common scenarios

Conditional 3DS

Use the following snippet to only trigger 3DS transactions above a certain amount.

class Conditional3DSManager(private val transactionAmount: Double) {
    
    fun createCardSubmitConfig(): CardSubmitComponentConfig {
        return CardSubmitComponentConfig(
onPreInitiateAuthentication = {
                if (transactionAmount > 100.0) {
    PreInitiateIntegratedAuthenticationData(
                        acquirerProfileId = "your_profile",
                        providerId = "your_provider",
                        requestorAuthenticationIndicator = RequestorAuthenticationIndicatorType.PAYMENT_TRANSACTION,
                        timeout = 120
                    )
                } else {
                    // Return null to skip 3DS for small amounts
                    null
                }
            }
        )
    }
}

Different transaction types

Use the following snippet to handle different types of transactions.

class TransactionType3DSManager {
    
    fun get3DSConfig(transactionType: TransactionType): PreInitiateIntegratedAuthenticationData {
        val baseConfig = PreInitiateIntegratedAuthenticationData(
            acquirerProfileId = "your_profile",
            providerId = "your_provider",
            timeout = 120
        )

        return when (transactionType) {
            TransactionType.PAYMENT -> baseConfig.copy(
                requestorAuthenticationIndicator = RequestorAuthenticationIndicatorType.PAYMENT_TRANSACTION
            )
            TransactionType.RECURRING -> baseConfig.copy(
                requestorAuthenticationIndicator = RequestorAuthenticationIndicatorType.RECURRING_TRANSACTION
            )
            TransactionType.ADD_CARD -> baseConfig.copy(
                requestorAuthenticationIndicator = RequestorAuthenticationIndicatorType.ADD_CARD
            )
        }
    }
    
    fun createCardSubmitConfig(transactionType: TransactionType): CardSubmitComponentConfig {
        return CardSubmitComponentConfig(
            onPreInitiateAuthentication = {
                get3DSConfig(transactionType)
            }
        )
    }
}

enum class TransactionType {
    PAYMENT, RECURRING, ADD_CARD
}

Step 4: Handle errors

Lastly, make sure to implement proper error handling.

class ThreeDS3DSErrorHandler {
    
    fun createCardSubmitConfigWithErrorHandling(): CardSubmitComponentConfig {
        return CardSubmitComponentConfig(
            onSubmitError = { error ->
                Log.e("3DS", "Payment error: $error")
                handleSubmitError(error)
            },

            onPostAuthentication = { authResult, threeDSData ->
                // Handle authentication failures
                when (authResult) {
                    is FailedAuthenticationResult -> {
                        Log.e("3DS", "Authentication failed: ${authResult.errorReason}")
                        // Don't proceed to authorisation
                        return@CardSubmitComponentConfig
                    }
                    is InitiateIntegratedSuccessAuthenticationResult -> {
                        // Check 3DS status
                        if (threeDSData?.state == "AuthenticationFailed") {
                            showError("Card authentication failed")
                            return@CardSubmitComponentConfig
                        }
                        Log.d("3DS", "Authentication successful, proceeding to payment")
                    }
                }
            }
        )
    }
    
    private fun handleSubmitError(error: PaymentError) {
        // Handle specific 3DS errors
        when (error.code) {
            "AUTHENTICATION_FAILED" -> {
                showError("Payment authentication failed. Please try again.")
            }
            "CHALLENGE_TIMEOUT" -> {
                showError("Authentication timed out. Please try again.")
            }
            "AUTHENTICATION_REJECTED" -> {
                showError("Payment was rejected by your bank.")
            }
            "TOKEN_VAULT_EXCEPTION" -> {
                showError("Token vault exception.")
            }
            "VALIDATION_EXCEPTION" -> {
                showError("Validation failed.")
            }
            "TRANSACTION_AUTHENTICATION_REJECTED" -> {
                showError("Payment was rejected by your bank.")
            }
            "PRE_INITIATE_AUTHENTICATION_FAILED" -> {
                showError("Pre-initiate authentication failed.")
            }
            "TRANSACTION_AUTHENTICATION_REQUIRES_SCA_EXEMPTION" -> {
                showError("Transaction authentication requires SCA exemption.")
            }
            "TRANSACTION_AUTHENTICATION_INVALID" -> {
                showError("Transaction authentication is invalid.")
            }
            "NETWORK_SDK_EXCEPTION" -> {
                showError("Network error occurred. Please try again.")
            }
            "UNEXPECTED_SDK_EXCEPTION" -> {
                showError("Payment failed. Please try again.")
            }
            else -> {
                showError("Payment failed. Please try again.")
            }
        }
    }
    
    private fun showError(message: String) {
        // Implementation depends on your UI framework
        Log.e("3DS", message)
    }
}

Complete example

The following example shows a simple 3DS implementation using the new card component in a complete Android Activity.

class ThreeDSPaymentActivity : ComponentActivity() {
    private lateinit var pxpCheckout: PxpCheckout
    private lateinit var newCardComponent: NewCardComponent
    private lateinit var errorHandler: ThreeDS3DSErrorHandler
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        setupPxpCheckout()
        setupComponents()
        
        setContent {
                ThreeDSPaymentScreen()
        }
    }
    
    private fun setupPxpCheckout() {
        val sdkConfig = PxpSdkConfig(
            environment = Environment.TEST,
            session = SessionConfig(
                sessionId = "session-${System.currentTimeMillis()}",
                sessionData = "your_session_data"
            ),
            transactionData = TransactionData(
                amount = 99.99,
                currency = CurrencyType.USD,
                entryType = EntryType.ECOM,
                intent = IntentType.AUTHORISATION,
                merchantTransactionId = "order-${System.currentTimeMillis()}",
                merchantTransactionDate = { Instant.now().toString() },
                shopper = Shopper(
                    email = "customer@example.com",
                    firstName = "John",
                    lastName = "Doe"
                )
            ),
            clientId = "your_client_id",
            ownerId = "Unity",
            ownerType = "MerchantGroup",
            merchantShopperId = "shopper-123"
        )
        
        pxpCheckout = PxpCheckout.builder()
            .withConfig(sdkConfig)
            .withContext(this)
            .withDebugMode(true)
            .build()
    }
    
    private fun setupComponents() {
        errorHandler = ThreeDS3DSErrorHandler()
        
        val newCardConfig = NewCardComponentConfig(
            submit = CardSubmitComponentConfig(
                // Step 1: Set up 3DS
                onPreInitiateAuthentication = {
                    PreInitiateIntegratedAuthenticationData(
                        acquirerProfileId = "your_acquirer_profile_id",
                        providerId = "your_3ds_provider_id",
                        requestorAuthenticationIndicator = RequestorAuthenticationIndicatorType.PAYMENT_TRANSACTION,
                        timeout = 120
                    )
                },

                // Step 2: Configure authentication
                onPreAuthentication = { preInitResult ->
                    InitiateIntegratedAuthenticationData(
                        merchantCountryNumericCode = "840",
                        merchantLegalName = "Your Company Ltd",
                        challengeWindowSize = "04",
                        requestorChallengeIndicator = "01",
                        challengeCallbackUrl = "https://your-domain.com/3ds-callback",
                        timeout = 300
                    )
                },

                // Step 3: Handle final authorisation
                onPreAuthorisation = { preAuthData, error ->
                    Log.d("3DS", "Pre-authorisation data: $preAuthData")
                    preAuthData.transactionInitiationData
                },

                // Step 4: Handle success/failure
                onPostAuthorisation = { result ->
                    when (result) {
                        is AuthorizedSubmitResult -> {
                            navigateToSuccessScreen()
                        }
                        is CapturedSubmitResult -> {
                            navigateToSuccessScreen()
                        }
                        is RefusedSubmitResult -> {
                            showError("Payment was declined: ${result.stateData.message}")
                        }
                        else -> {
                            showError("Payment failed")
                        }
                    }
                },

                // Step 5: Error handling
                onSubmitError = { error ->
                    Log.e("3DS", "3DS Error: $error")
                    showError("Payment authentication failed")
                }
            )
        )
        
        newCardComponent = pxpCheckout.createComponent(ComponentType.NEW_CARD, newCardConfig)
    }
    
    @Composable
    private fun ThreeDSPaymentScreen() {
        var isLoading by remember { mutableStateOf(false) }
        var errorMessage by remember { mutableStateOf<String?>(null) }
        var authenticationState by remember { mutableStateOf<String?>(null) }
        
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(16.dp)
        ) {
            Text(
                text = "3DS Secure Payment",
                style = MaterialTheme.typography.headlineMedium,
                modifier = Modifier.padding(bottom = 16.dp)
            )
            
            // Show authentication status
            authenticationState?.let { state ->
                Card(
                    colors = CardDefaults.cardColors(containerColor = Color.Blue.copy(alpha = 0.1f)),
                    modifier = Modifier
                        .fillMaxWidth()
                        .padding(bottom = 16.dp)
                ) {
            Text(
                        text = "Authentication Status: $state",
                        color = Color.Blue,
                        modifier = Modifier.padding(16.dp)
                    )
                }
            }
            
            // Show error message if any
            errorMessage?.let { message ->
                Card(
                    colors = CardDefaults.cardColors(containerColor = Color.Red.copy(alpha = 0.1f)),
                    modifier = Modifier
                        .fillMaxWidth()
                        .padding(bottom = 16.dp)
                ) {
                    Text(
                        text = message,
                        color = Color.Red,
                        modifier = Modifier.padding(16.dp)
                    )
                }
            }
            
            // Render payment components
            pxpCheckout.buildComponentView(
                component = newCardComponent,
                modifier = Modifier.fillMaxWidth()
            )
            
            // Loading indicator
            if (isLoading) {
                Box(
                    modifier = Modifier.fillMaxWidth(),
                    contentAlignment = Alignment.Center
                ) {
                    CircularProgressIndicator()
                    Text(
                        text = "Processing 3DS Authentication...",
                        modifier = Modifier.padding(top = 60.dp)
                    )
                }
            }
        }
    }
    
    private fun navigateToSuccessScreen(transactionId: String?) {
        val intent = Intent(this, PaymentSuccessActivity::class.java).apply {
            putExtra("transaction_id", transactionId)
            putExtra("payment_type", "3ds")
        }
        startActivity(intent)
        finish()
    }
    
    private fun showError(message: String) {
        AlertDialog.Builder(this)
            .setTitle("3DS Payment Error")
            .setMessage(message)
            .setPositiveButton("OK") { dialog, _ ->
                dialog.dismiss()
            }
            .show()
    }
}

Callback data

This section describes the data received by the different callbacks as part of the 3DS flow.

The onPreInitiateAuthentication callback doesn't receive anything so isn't included. Instead, it returns your 3DS configuration in the PreInitiateAuthenticationData object.

onPostInitiateAuthentication

The onPostInitiateAuthentication callback receives an authentication result (AuthenticationResult) that can be either a success (PreInitiateSuccessAuthenticationResult) or a failure (FailedAuthenticationResult).

Success

When successful, onPostInitiateAuthentication receives the following PreInitiateSuccessAuthenticationResult.

PreInitiateSuccessAuthenticationResult(
    authenticationId = "auth_12345",
    state = "PendingClientData",
    scaMandated = true,
    applicableExemptions = "LVP"
)

Parameter	Description
`authenticationId`	The unique identifier for this 3DS session.
`state`	The state of the authentication. Possible values: `AuthenticationSuccessful` `AuthenticationFailed` `AuthenticationRejected` `AuthenticationError` `PendingCustomerChallenge` `PendingClientData`
`scaMandated`	Whether Strong Customer Authentication (SCA) is required.
`applicableExemptions`	The list of exemptions that apply to this transaction. Possible values: `LVP`: Low-value payment `TRA`: Transaction risk analysis

Here's an example of what to do with this data:

onPostInitiateAuthentication = { result ->
    when (result) {
        is FailedAuthenticationResult -> {
            // This is a failure - ignore or log briefly
            Log.w("3DS", "3DS pre-initiation failed - skipping processing")
            return@onPostInitiateAuthentication
        }
        is PreInitiateSuccessAuthenticationResult -> {
            // This is a success - process it
            Log.d("3DS", "3DS Authentication ID: ${result.authenticationId}")
            
            // Check if SCA (Strong Customer Authentication) is mandated
            if (result.scaMandated) {
                Log.d("3DS", "SCA is required - 3DS must complete successfully")
                // Show user message: "Additional verification required"
                showUserMessage("Additional verification required")
            }
            
            // Check available exemptions
            when (result.applicableExemptions) {
                "LVP" -> {
                    Log.d("3DS", "Low value exemption available")
                    // You might skip 3DS for small amounts
                }
                "TRA" -> {
                    Log.d("3DS", "Transaction risk analysis exemption available")
                }
            }
            
            // Check the current state
            when (result.state) {
                "PendingClientData" -> {
                    Log.d("3DS", "Waiting for client data collection")
                    updateAuthenticationState("Collecting device data...")
                }
                "AuthenticationSuccessful" -> {
                    Log.d("3DS", "Authentication already completed successfully")
                    updateAuthenticationState("Authentication successful")
                }
                "AuthenticationFailed" -> {
                    Log.d("3DS", "Authentication failed")
                    updateAuthenticationState("Authentication failed")
                }
                "PendingCustomerChallenge" -> {
                    Log.d("3DS", "Challenge required from customer")
                    updateAuthenticationState("Challenge required")
                }
                else -> {
                    Log.d("3DS", "Authentication state: ${result.state}")
                    updateAuthenticationState(result.state)
                }
            }
        }
    }
}

private fun showUserMessage(message: String) {
    // Show user-friendly message
    Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
}

private fun updateAuthenticationState(state: String) {
    // Update UI with authentication state
    Log.d("3DS", "Authentication state updated: $state")
}

Failure

When unsuccessful, onPostInitiateAuthentication receives the following FailedAuthenticationResult.

FailedAuthenticationResult(
    errorCode = "3DS_001",
    errorReason = "Invalid acquirer profile",
    correlationId = "corr_98765",
    details = listOf(
        "The specified acquirer profile is not valid",
        "Please check your configuration"
    ),
    status = 400
)

Parameter	Description
`errorCode`	The error code.
`errorReason`	The reason for the error.
`correlationId`	The correlation ID.
`details`	Additional details about the error.
`status`	The HTTP status code.

onPreAuthentication

The onPreAuthentication callback receives a PreInitiateSuccessAuthenticationResult (from the pre-initiate step) and should return InitiateIntegratedAuthenticationData.

Here's an example of what to do with this data:

onPreAuthentication = { preInitResult ->
    Log.d("3DS", "Received pre-initiation data: $preInitResult")
    
    // Use the authentication ID to track this transaction
    val authId = preInitResult.authenticationId
    Log.d("3DS", "Proceeding with authentication ID: $authId")
    
    // Check if SCA is mandated to adjust challenge preference
    val challengeIndicator = when {
        preInitResult.scaMandated -> {
            Log.d("3DS", "SCA mandated - requesting challenge")
            "03" // Challenge mandated
        }
        preInitResult.applicableExemptions == "LVP" -> {
            Log.d("3DS", "Low value exemption - requesting no challenge")
            "04" // No challenge requested
        }
        preInitResult.applicableExemptions == "TRA" -> {
            Log.d("3DS", "TRA exemption - requesting no challenge")
            "04" // No challenge requested
        }
        else -> {
            "01" // No preference
        }
    }
    
    val timeout = if (preInitResult.scaMandated) 600 else 300
    
    InitiateIntegratedAuthenticationData(
        merchantCountryNumericCode = "840",
        merchantLegalName = "Your company name",
        challengeWindowSize = "04",
        requestorChallengeIndicator = challengeIndicator,
        challengeCallbackUrl = "https://your-domain.com/3ds-callback",
        timeout = timeout
    )
}

onPostAuthentication

The onPostAuthentication callback receives:

An authentication result (AuthenticationResult). This can be either a success (InitiateIntegratedSuccessAuthenticationResult) or a failure (FailedAuthenticationResult).
The 3DS authentication data (ThreeDSAuthenticationData) if a challenge occurred.

3DS Authentication Details

ThreeDSAuthenticationData(
    authenticationId = "auth_12345",
    state = "AuthenticationSuccessful",
    threeDSecureVersion = "2.2.0",
    directoryServerTransactionId = "ds_trans_id",
    cardHolderAuthenticationVerificationValue = "cavv_value_here",
    electronicCommerceIndicator = "05"
)

Parameter	Description
`authenticationId`	The unique identifier for this 3DS session.
`state`	The state of the authentication. Possible values: `AuthenticationSuccessful` `AuthenticationFailed` `AuthenticationRejected` `AuthenticationError`
`threeDSecureVersion`	The 3DS secure version.
`directoryServerTransactionId`	The transaction ID assigned by the Directory Server.
`cardHolderAuthenticationVerificationValue`	The cardholder authentication verification value (CAVV).
`electronicCommerceIndicator`	The Electronic Commerce Indicator (ECI). Possible values: `01` `02` `05` `06` `07`

Authentication result

Success

InitiateIntegratedSuccessAuthenticationResult(
    uniqueId = "unique_12345",
    state = "completed",
    transactionStatus = "Y", // AuthenticationVerificationSuccessful
    electronicCommerceIndicator = "05", // 3DS authenticated
    exemptionGranted = false,
    exemptionGrantedByIssuer = "79", // NoExemptionApplied
    acsUrl = null, // No challenge needed
    challengeData = null, // No challenge needed
    stateData = StateData(
        code = "success",
        reason = "Authentication completed successfully"
    ),
    cardholderInfo = null
)

Parameter	Description
`uniqueId`	The unique identifier for this 3DS session.
`state`	The state of the authentication.
`transactionStatus`	The status of the transaction. Possible values: `Y`: Authentication verification successful `N`: Not authenticated / not verified `U`: Authentication couldn't be performed `A`: Attempts processing performed `C`: Challenge required `R`: Authentication rejected `I`: Informational only
`electronicCommerceIndicator`	The Electronic Commerce Indicator (ECI). Possible values: `01`: 3DS not available (non-3DS transaction) `02`: 3DS available but not used `05`: 3DS authentication successful (fully authenticated) `06`: 3DS authentication attempted `07`: 3DS authentication failed but transaction allowed
`exemptionGranted`	Whether an exemption was granted.
`exemptionGrantedByIssuer`	The type of exemption granted by the issuer. Possible values: `05`: Transaction risk analysis exemption `08`: Trust list exemption `10`: Low value exemption `11`: Secure corporate payments exemption `79`: No exemption applied
`acsUrl`	The ACS URL.
`challengeData`	Base64 encoded challenge data.
`stateData`	Details about the state.
`cardholderInfo`	Additional details about the cardholder.

Here's an example of what to do with this data:

onPostAuthentication = { authResult, threeDSData ->
    Log.d("3DS", "Authentication result: $authResult")
    Log.d("3DS", "3DS data: $threeDSData")
    
    when (authResult) {
        is FailedAuthenticationResult -> {
            Log.e("3DS", "Authentication failed: ${authResult.errorReason}")
            showError("Card verification failed. Please try a different payment method.")
            return@onPostAuthentication // Stop the payment flow
        }
        is InitiateIntegratedSuccessAuthenticationResult -> {
            // Check transaction status
            when (authResult.transactionStatus) {
                "Y" -> {
                    Log.d("3DS", "Authentication successful - no challenge needed")
                    showMessage("Card verified successfully")
                }
                "C" -> {
                    Log.d("3DS", "Challenge completed - checking result...")
                    if (threeDSData?.state == "AuthenticationSuccessful") {
                        Log.d("3DS", "Challenge completed successfully")
                        showMessage("Verification completed")
                    } else {
                        Log.e("3DS", "Challenge failed")
                        showError("Verification failed. Please try again.")
                        return@onPostAuthentication // Stop payment
                    }
                }
                "N" -> {
                    Log.e("3DS", "Authentication failed")
                    showError("Card verification failed")
                    return@onPostAuthentication // Stop payment
                }
                "R" -> {
                    Log.e("3DS", "Authentication rejected")
                    showError("Payment was rejected by your bank")
                    return@onPostAuthentication // Stop payment
                }
            }
            
            // Log important 3DS data for transaction
            threeDSData?.let { data ->
                Log.d("3DS", "ECI: ${data.electronicCommerceIndicator}")
                Log.d("3DS", "CAVV: ${data.cardHolderAuthenticationVerificationValue}")
                // These values prove successful 3DS authentication
            }
            
            Log.d("3DS", "Proceeding to final authorisation...")
        }
    }
}

private fun showMessage(message: String) {
    Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
}

private fun showError(message: String) {
    AlertDialog.Builder(this)
        .setTitle("Authentication Error")
        .setMessage(message)
        .setPositiveButton("OK") { dialog, _ -> dialog.dismiss() }
        .show()
}

onPreAuthorisation

The onPreAuthorisation callback receives:

Pre-authorisation data (preAuthData): Transaction data ready for authorisation.
Error data (error): Any error that occurred during pre-authorisation.

The callback should return the final TransactionInitiationData to be used for authorisation.

Pre-authorisation data

The pre-authorisation data includes transaction initiation data (for new cards) or card token data (for saved cards).

PreAuthorisationData(
    transactionInitiationData = TransactionInitiationData(
        psd2Data = PSD2Data(
            scaExemption = null
        ),
        threeDSecureData = ThreeDSecureData(
            threeDSecureVersion = "2.2.0",
            electronicCommerceIndicator = "05",
            cardHolderAuthenticationVerificationValue = "jGvQIvG/5UhjAREALGYYemQLXPI=",
            directoryServerTransactionId = "ds_trans_12345",
            threeDSecureTransactionStatus = "Y"
        ),
        identityVerification = IdentityVerification(
            nameVerification = true
        ),
        addressVerification = AddressVerification(
            countryCode = "US",
            houseNumberOrName = "123",
            postalCode = "10001"
        )
    )
)

Here's an example of what to do with this data:

onPreAuthorisation = { preAuthData, error ->
    Log.d("3DS", "Final authorisation data: $preAuthData")
    
    if (error != null) {
        Log.e("3DS", "Pre-authorisation error: ${error.message}")
        showError("Payment processing error: ${error.message}")
        return@onPreAuthorisation null // Cancel the transaction
    }
    
    // Get the base transaction data
    val transactionData = preAuthData.transactionInitiationData
    
    // Add any additional data you need
    val finalTransactionData = transactionData?.copy(
        // Add custom metadata
        metadata = mapOf(
            "authenticationId" to "auth_12345",
            "timestamp" to Instant.now().toString()
        ),
        
        // Add shipping info if needed
        shippingAddress = ShippingAddress(
            addressLine1 = "123 Main St",
            city = "New York",
            postalCode = "10001",
            countryCode = "US"
        )
    )
    
    Log.d("3DS", "Sending final transaction for authorisation")
    finalTransactionData
}

3DS transactions

Overview

Payment flow

Step 1: Submission

Step 2: Card tokenisation

Step 3: Evaluation

Step 4: Pre-initiation

Step 5: Fingerprinting

Step 6: Authentication

Step 7: Authentication result

Step 8: Authorisation

Step 9: Authorisation result

Additional 3DS callbacks

Authentication status callbacks

Challenge flow callbacks

Implementation

Before you start

Step 1: Configure your SDK

Step 2: Implement callbacks

Step 3: Handle common scenarios

Conditional 3DS

Different transaction types

Step 4: Handle errors

Complete example

Callback data

onPostInitiateAuthentication

Success

Failure

onPreAuthentication

onPostAuthentication

3DS Authentication Details

Authentication result

Success

onPreAuthorisation

Pre-authorisation data

Was this helpful?