# Authenticate a 3D-Secure Transaction with a Password and One-Time Passcode Sent by the Issuer
source: https://developer.mastercard.com/mastercard-processing-authentication/documentation/use-cases/auth-trans-with-pass-otp-iss/index.md

## Overview {#overview}

The use case describes the process for a cardholder to authenticate a 3D-Secure (3DS) transaction using the password and the one-time passcode (OTP) generated by the ACS provider but sent to the cardholder by the issuer through SMS.


Tip: Suppose you want to use the Mastercard Processing Authentication Hub API to always authenticate 3DS transactions with the OTP sent by you. In this case, you can decide during the onboarding process to use the Authentication Lite solution. The integration will be simplified because you will not need to implement any authentication method decision logic that you must provide in the `acsAReq` response. In the Authentication Lite solution, the `acsAReq` request is omitted by the ACS provider, and the initial request that you will receive from the ACS provider will be forwarded to you by the Mastercard Processing Authentication Hub API will be the `acsNewOtp`. Refer to [Authenticate a 3D-Secure Transaction with a Password and One-Time Passcode Sent by the Issuer (Lite solution)](https://developer.mastercard.com/mastercard-processing-authentication/documentation/use-cases/auth-trans-with-pass-otp-iss-lite/index.md) for more information. 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: This authentication method does not comply with PSD2 2FA requirements and can be used only outside the EEA and the UK. 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.

<br />

## Sequence diagram {#sequence-diagram}

Diagram auth-trans-pass-otp-iss

## 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 `7` 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`. 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 the cardholder to enter the verification code sent to the cardholder mobile number by SMS. Alert: Ensure the cardholder mobile phone number is provided during the client object creation or update in the CMS using the [Mastercard Processing Core API](https://developer.mastercard.com/mastercard-processing-core/documentation/). Only then will the mobile phone number be automatically enrolled in the ACS. Otherwise, the ACS provider will display that the card has no registered mobile phone number on the authentication page. 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 server sends the OTP, generated by the ACS server, to the cardholder by SMS.
12. Optionally, the cardholder clicks to resend the OTP on the authentication page if the SMS was not delivered for some reason.
13. The ACS server sends the `acsNewOtp` request to the Mastercard Processing Authentication Hub API with the `otp` field containing a newly generated OTP.
14. 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.

15. The Mastercard Processing Authentication Hub API forwards the `acsNewOtp` request to the server by sending `POST` request to the `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/one-time-passcodes` endpoint.
16. The server returns the HTTP status `200` to the Mastercard Processing Authentication Hub API.
17. The Mastercard Processing Authentication Hub API forwards the HTTP status `200` to the ACS provider.
18. The server sends the OTP from step 15 directly to the cardholder through SMS.
19. The cardholder enters the OTP received by SMS and their password on the authentication page rendered by the ACS server.
20. The OTP and password verification result is presented to the cardholder.
21. The ACS provider sends the authentication result to the DS, which routes the result to the merchant.
22. The merchant displays the authentication status to the cardholder.
23. 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.
24. 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.

25. 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.
26. The server returns the HTTP status `200` to the Mastercard Processing Authentication Hub API.
27. The Mastercard Processing Authentication Hub API forwards the HTTP status `200` to the ACS provider.

## Endpoints {#endpoints}

`acsAReq`

API Reference: `POST /three-ds-transactions/{three_ds_server_transaction_id}/acs-authentication-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`