# EMV 3-D Secure Authentication
source: https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/3d-secure-auth/index.md

EMV 3-D Secure authentication is designed to protect online purchases against credit card fraud by allowing you to authenticate the payer before you submit an AUTHORIZE or PAY transaction. The EMV 3-D Secure feature of the gateway and the authentication within the Mobile SDK are limited to 3DS2 only. If EMV 3-D Secure is not available, the authentication does not proceed. However, you can still proceed with the payment if the gateway recommends you do so. For more information about the gateway's EMV 3-D Secure feature in general, see [EMV 3-D Secure Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md).

To authenticate the payer:

1. Use your server to update the session with all the relevant details that can help the authentication to proceed smoother.
2. Ask the SDK to perform the authentication.
3. Interpret the results returned by the SDK.

## Updating the session with authentication details {#updating-the-session-with-authentication-details}

When you perform Mobile SDK authentication (verify the identity of a cardholder in a mobile app), the Mobile SDK collects device metrics to send to the gateway along with your transaction information.

Provide as much information about the payer and the transaction as possible to increase the likelihood of the authentication being successful. You can [add the fields](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/index.md) in the following table to your session with an [UPDATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) request.

### Optional UPDATE SESSION fields {#optional-update-session-fields}

|            Field             |                                                                     Description                                                                     |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `order.merchantCategoryCode` | Merchant category code. This value is only needed if it differs from the code that has been defined for the acquirer link in your merchant profile. |
| `billing.address` object     | Payer's billing address. It is recommended you include this in your request whenever possible.                                                      |
| `shipping.address` object    | Address where this order will be shipped. It is recommended you include this in your request whenever possible.                                     |
| `customer` object            | Information associated with the payer's account. It is recommended you include this in your request whenever possible.                              |

Warning: The device object defined in the API Reference is only relevant for [browser-based payments](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/index.md). Do not use it for mobile-based payer authentication.

The above fields help the system to determine how or if to authenticate the cardholder. During authentication, the user goes through one of the following authentication flows:

* **Frictionless flow**: The Access Control Server (ACS) has collected enough information about the cardholder to authenticate them. No other action is needed by the user.

* **Challenge flow**: The ACS requires the cardholder to complete an additional authentication step, which is to enter a onetime password, log in to their issuing bank, or something similar. The embedded Mobile SDK handles displaying a native device interface for this challenge. The UI for these screens can be customized by passing UI Customization fields into the Mobile SDK during initialization.

For more information, see [EMV 3-D Secure Authentication Flow](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md).
Warning: The object for `authentication.PSD2.exemption` is currently not supported in the SDK.

## Performing authentication {#performing-authentication}

Payer authentication is considered a transaction on its own in the gateway, and therefore needs a unique transaction ID.

If you are collecting a payment for an order:

* You can correlate a payment and an authentication transaction by using the same order ID for each transaction (for example, UUID).
* Each transaction is displayed as a separate transaction in the Merchant Administration.
* When integrating 3DS2 using the SDK, submit the [INITIATE_AUTHENTICATION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request with `authentication.channel = PAYER_APP`.

To start the authentication process in the SDK, call the `authenticate()` function.

### Example code for iOS {#example-code-for-ios}

```swift
let request = AuthenticationRequest(
    navController: navController,
    apiVersion: apiVersion,
    sessionId: sessionId,
    orderId: orderId,
    transactionId: authenticationTxnId
)

AuthenticationHandler.shared.authenticate(request) { response in
    // Handle response
}
```

Warning: `authenticationTxnId` is a unique ID for this transaction which distinguishes it from any other transaction within the same order. When you send the actual payment transaction request (such as PAY), the gateway uses this ID to look up the authentication results that are stored when you ask the SDK to authenticate the payer. The gateway passes the authentication results to the acquirer along with the payment transaction request.

### Example code for Android {#example-code-for-android}

```kotlin
AuthenticationHandler.authenticate(
    activityContext,
    session,
    "your-auth-transaction-id",
    callback
)
```

Warning: `your-auth-transaction-id` is a unique ID for this transaction which distinguishes it from any other transaction within the same order. When you send the actual payment transaction request (such as PAY), the gateway uses this ID to look up the authentication results that are stored when you ask the SDK to authenticate the payer. The gateway passes the authentication results to the acquirer along with the payment transaction request.

### Interpreting the response {#interpreting-the-response}

The authenticate function returns an `AuthenticationResponse` object that contains:

* Important information about the outcome
* Actions performed during the operation.

The most important field to check is `response.recommendation`. It can contain the following values:

* PROCEED: You can continue with a payment or authorization.
* DO_NOT_PROCEED: Something failed during the authentication operation. Use the `AuthenticationError` object to find out more.

From Mastercard Gateway API version 70 and later, you can get the following errors:

* `AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails`: Ask the payer for alternative payment details, for example, a new card or another payment method, and resubmit the request with the new details.
* `AuthenticationError.recommendation_AbandonOrder`: The Payment Service Provider (PSP), scheme, or issuer requires you to abandon the order.
* `AuthenticationError.recommendation_DoNotProceed`: The gateway fails the request, and there is no way for this transaction to succeed.

If the authentication fails, you can also examine response.error for more information about any other errors sent by the gateway.

### Example code for iOS {#example-code-for-ios-1}

```swift
AuthenticationHandler.shared.authenticate(request) { response in
    DispatchQueue.main.async {
        switch response.recommendation {
        case .doNotProceed:
            if let error = response.error {
                print("SDK Error: \(error.localizedDescription)")
                
                if let authError = error as? AuthenticationError,
                   authError == .recommendation_ResubmitWithAlternativePaymentDetails {
                    // Authentication not successful, re-enter card details
                }
            }
            // Authentication not successful

        case .proceed:
            // Proceed to submit the payment, authorization etc.

        @unknown default:
            // Handle unexpected recommendation
        }
    }
}
```

### Example code for Android {#example-code-for-android-1}

```kotlin
AuthenticationHandler.authenticate(
    activityContext,
    session,
    "your-auth-transaction-id"
) { response ->
    when (response.recommendation) {
        AuthenticationRecommendation.PROCEED -> {
            // Continue to payment/authorization
        }

        AuthenticationRecommendation.DO_NOT_PROCEED -> {
            if (response.error != null) {
                if (response.error is AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
                    // Authentication not successful, re-enter card details
                }
            } else {
                // Authentication not successful
            }
        }
    }
}
```