# Authenticate a 3D-Secure Transaction with an Issuer's Mobile Application or a One-Time Passcode and Password
source: https://developer.mastercard.com/mastercard-processing-authentication/documentation/use-cases/auth-trans-with-iss-mob-app-alt/index.md

## Overview {#overview}

The use case describes the process for a cardholder to authenticate a 3D-Secure (3DS) transaction with two alternative scenarios that the cardholder can choose, either using the issuer's mobile application or one-time passcode (OTP) and password.

Tip: The use case depicts the OTP sent by the issuer, but depending on the issuer configuration, the OTP can be sent by the ACS.

<br />

Note: To simplify the sequence diagram, the 3DS Server and Directory Server have been omitted. However, merchants and ACS providers communicate through the 3DS Server (or 3DS SDK) and Mastercard Directory Server, which are part of the Acquirer domain and Interoperability domain, respectively. Alert: There is a 3-second timeout set at the Mastercard API Gateway level for all outbound calls. However, it is strongly recommended to ensure that your endpoint responds quickly, within 1.5 seconds, to prevent the 3DS secure transaction from failing due to a timeout on the ACS or DS side.

## Sequence diagram {#sequence-diagram}

Diagram auth-trans-iss-mob-app-alt

## Explanation {#explanation}

1. The cardholder decides to initiate a payment with a card at the e-commerce merchant.
2. The merchant initiates the 3DS process using its 3DS server that sends the authentication request to the Mastercard DS, which routes the request to the Mastercard Processing ACS provider.
3. The ACS provider decides that the authentication will be non-frictionless based on the issuer configuration and sends the authentication request (`acsAReq`) to the Mastercard Processing Authentication Hub API. Note: In the standard Authentication Hub setup, the ACS provider forwards all authentication requests to the issuer. However, once the onboarding process is completed, the issuer will have access to the ACS admin panel, where they can maintain their configuration, including creating frictionless rules that can be applied at the ACS level.
4. The Mastercard Processing Authentication Hub API adds the following details to the `acsAReq` request body:

* Technical card identifiers (`cardContractId` and `cbsNumber`) linked in the CMS with the `cardContractNumber` received from the ACS provider in the `acsAReq` request. Note: For PAN-less issuers, the Mastercard Processing Authentication Hub API can be configured to mask the full PAN received from the ACS Provider in the `cardContractNumber` field before forwarding the request to the issuer. For the Authentication Hub API, the PAN masking pattern cannot be modified and is the following:
  * The first six and last four digits are visible.
  * All others are replaced with \*.

  For example, 512345\*\*\*\*\*\*2345.

5. The Mastercard Processing Authentication Hub API forwards the `acsAReq` request to the server by sending the `POST` request to the `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/acs-authentication-requests` endpoint.
6. The server decides to authenticate the cardholder with the mobile application. It returns the response with the body, containing value `3c` in the `authenticationMethod` field and `staticPasscode` field with the hash value of the cardholder's password, to the Mastercard Processing Authentication Hub API. Tip: Instead of sending the cardholder password each time in the `acsAReq` response, you can enroll it in the ACS using the [Core API `setAuthenticationMethod`](https://developer.mastercard.com/mastercard-processing-core/documentation/use-cases/card-lifecycle/set-update-auth-method/). To do that, you must send the `setAuthenticationMethod` request with the following request body:

   ```json
   {
     "authenticationParameters": [
       {
         "name": "PASSWORD",
         "value": "hashed_password"
       }
     ],
     "authenticationTypeCode": "3DS_EXT_ENROLLMENT"
   }
   ```

   In the `value` field, you must send the cardholder password hashed using the algorithm agreed with the ACS provider.
7. The Mastercard Processing Authentication Hub API forwards the issuer response to the `acsAReq` request to the ACS provider.
8. The ACS provider sends the authentication result to the DS, which routes the result to the merchant.
9. The merchant sends the challenge request to the ACS provider through the DS.
10. The ACS provider displays the authentication page to the cardholder. The authentication page informs that a push notification will be sent to the cardholder mobile device to verify the transaction in the issuer mobile application. The authentication page also displays a **Choose an alternative method** button. Note: The authentication page template can be customized to your needs during the onboarding process. Later, you can manage page templates using the ACS admin panel.
11. The ACS provider parallelly sends the challenge request (`acsCReq`) to the Mastercard Processing Authentication Hub API.
12. The Mastercard Processing Authentication Hub API adds the following details to the `acsCReq` request body:

* Technical card identifiers (`cardContractId` and `cbsNumber`) linked in the CMS with the `cardContractNumber` received from the ACS provider in the `acsCReq` request.

13. The Mastercard Processing Authentication Hub API forwards the `acsCReq` request to the server by sending the `POST` request to the `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/acs-challenge-requests` endpoint.
14. The server returns the HTTP status `200` to the Mastercard Processing Authentication Hub API.
15. The Mastercard Processing Authentication Hub API forwards the HTTP status `200` to the ACS provider.
16. In parallel to step 14, the server notifies the issuer mobile application to authenticate the cardholder for the 3DS transaction.
17. The issuer application sends the push notification to the cardholder mobile device to verify the 3DS transaction.
18. The cardholder successfully authenticates on the issuer mobile application to confirm the 3DS transaction.
19. The issuer application sends the confirmation to the server.
20. The server sends the `issCRes` request by sending the `POST` request to the `/three-ds-transactions/{three_ds_server_transaction_id}/issuer-challenge-responses` endpoint with the `Y` value in the `transactionStatus` field in the request body. Note: The request body must be encrypted using JWE with the Client Encryption Key generated during your project creation in the Mastercard Developers. Refer to [Inbound calls](https://developer.mastercard.com/mastercard-processing-authentication/documentation/api-basics/index.md#encryption) for more information.
21. The Mastercard Processing Authentication Hub API forwards the request, containing the challenge response, from the server to the ACS provider.
22. Alternatively, to steps 16-21, the cardholder selects **Choose an alternative method** on the authentication page at step 10.
23. The ACS provider sends the `acsNewOtp` request to the Mastercard Processing Authentication Hub API with the `otp` field containing the generated OTP to inform the issuer that the cardholder switched to the OTP and password authentication method. Tip: The `otp` value sent in the `acsNewOtp` is the same as sent during the initial `acsAReq` call to avoid confusion since that first `otp` value has not been used.
24. The Mastercard Processing Authentication Hub API adds the following details to the `acsNewOtp` request body:

* Technical card identifiers (`cardContractId` and `cbsNumber`) linked in the CMS with the `cardContractNumber` received from the ACS provider in the `acsNewOtp` request.

25. The Mastercard Processing Authentication Hub API forwards the `acsNewOtp` request to the server by sending the `POST` request to the `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/one-time-passcodes` endpoint.
26. The server sends the OTP from step 25 directly to the cardholder through an SMS.
27. The cardholder enters the OTP and password on the authentication screen rendered by the ACS provider.
28. The OTP and password verification result is presented to the cardholder. Note: Optionally, the cardholder can click to resend the OTP on the authentication page if the SMS was not delivered for some reason. In that case, the following steps are executed:
    * The ACS server sends the `acsNewOtp` request to the Mastercard Processing Authentication Hub API with the `otp` field containing a newly generated OTP.
    * The Mastercard Processing Authentication Hub API adds the following details to the `acsNewOtp` request body:
      * Technical card identifiers (`cardContractId` and `cbsNumber`) linked in the CMS with the `cardContractNumber` received from the ACS provider in the `acsNewOtp` request.
    * The Mastercard Processing Authentication Hub API forwards the `acsNewOtp` request to the server by sending the `POST` request to the `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/one-time-passcodes` endpoint.
    * The server returns the HTTP status `200` to the Mastercard Processing Authentication Hub API.
    * The Mastercard Processing Authentication Hub API forwards the HTTP status `200` to the ACS provider.
29. Depending on the authentication method selected by the cardholder, after step 21 (for the issuer mobile application flow) or 28 (for the OTP and password flow), the ACS provider sends the authentication result to the DS, which routes the result to the merchant.
30. The merchant displays the authentication status to the cardholder.
31. The ACS provider sends the `acsCStatus` request to the Mastercard Processing Authentication Hub API. The `acsCStatus` request contains the final status of the authentication performed by the ACS provider.
32. The Mastercard Processing Authentication Hub API adds the following details to the `acsCStatus` request body:

* Technical card identifiers (`cardContractId` and `cbsNumber`) linked in the CMS with the `cardContractNumber` received from the ACS provider in the `acsCStatus` request. Note: For PAN-less issuers, the Mastercard Processing Authentication Hub API can be configured to mask the full PAN received from the ACS Provider in the `cardContractNumber` field before forwarding the request to the issuer. For the Authentication Hub API, the PAN masking pattern cannot be modified and is the following:
  * The first six and last four digits are visible.
  * All others are replaced with \*.

  For example, 512345\*\*\*\*\*\*2345.

33. The Mastercard Processing Authentication Hub API forwards the `acsCStatus` request to the server by sending the `POST` request to the `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/acs-challenge-statuses` endpoint.
34. The server returns the HTTP status `200` to the Mastercard Processing Authentication Hub API.
35. The Mastercard Processing Authentication Hub API forwards the HTTP status `200` to the ACS provider.

## Endpoints {#endpoints}

### Outbound APIs {#outbound-apis}

`acsAReq`

API Reference: `POST /three-ds-transactions/{three_ds_server_transaction_id}/acs-authentication-requests`

`acsCReq`

API Reference: `POST /three-ds-transactions/{three_ds_server_transaction_id}/acs-challenge-requests`

`acsNewOtp`

API Reference: `POST /three-ds-transactions/{three_ds_server_transaction_id}/one-time-passcodes`

`acsCStatus`

API Reference: `POST /three-ds-transactions/{three_ds_server_transaction_id}/acs-challenge-statuses`

### Inbound API {#inbound-api}

`issCRes`

API Reference: `POST /three-ds-transactions/{three_ds_server_transaction_id}/issuer-challenge-responses`