# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# Request a 3-D Secure (3DS) authentication

A 3DS authentication consists of the following steps:

1. Send a POST call to the /authentications endpoint.

2. Call the 3DS Method to collect data from the cardholder's browser.

3. Send a POST call to the /authentications/{authentication-id} endpoint.

4. Launch the issuer challenge screen (in instances when the issuer requires a challenge flow).

5. Listen for authentication results.

6. GET additional authentication details.

7. Process the payment (optional).

## POST to /authentications endpoint

A 3DS authentication begins with a `POST` call to the `/authentications` endpoint. This request does the following:

1. Verifies whether the card issuer supports3DS for the card. If so, the responseCode field will be set to CREATED.

2. Finds the common 3DS version supported by the 3DS server, card brand network directory server, and issuer access control server (ACS).

3. Retrieves the correct issuer URL needed to facilitate the issuer's cardholder browser data collection process.

**HTTP method**: `POST`
 **Endpoint**: `/authentications`

```json
{
    "amount": 123,
    "currency": "USD",
    "authenticationPaymentMethodType": {
        "accountNumber": "4112344112344113"
    },
    "threeDSMethodMerchantNotificationUrl": "example.com"
}
```

> By including the **threeDSMethodMerchantNotification** URL value in your request, you will be advised as soon as data collection is complete - reducing the friction in the flow. Not including the URL value in your request will require you wait up to a full 10 seconds to complete the next step.
> 

## Call the 3DS Method to collect data from the cardholder's browser

The response to your `/authentications` request will contain the following fields:

- authenticationResult.threeDomainSecureCreation.threeDSMethodDataForm

- authenticationResult.threeDSServerTransactionId

- authenticationResult.threeDomainSecureCreation.threeDSMethodUrl

The 3DS Method is completed by rendering a hidden HTML iframe in the cardholder’s browser to post a form with data from the aforementioned fields.

```
<form name="frm" method="POST" action="{threeDSMethodUrl"> 
<input type="hidden" name="{threeDSMethodData}" value=”{threeDSMethodDataForm}"> 
</form>
```

The 3DS Method will take up to 10 seconds to complete the issuer's collection of cardholder browser data.

Concurrently, you should collect the card holder’s browser data on your own to be used in the next step. The card issuer will compare the browser data collected by the 3DS Method against the browser data you collect as part of the authentication decision.

## POST to /authentications/{authentication-Id} endpoint

> Some fields can be supplied in a POST call to either the **/authentications** or **/authentications/{authenticationId}** endpoints. If they are supplied in both API calls, the values submitted in the POST to **/authentications/{authenticationId}** will be used.  
> 

After the 3DS Method is complete, the browser will post to the **threeDSMethodMerchantNotificationUrl** (provided in your the `/authentications` request) with the 3DS Method result. The post will include `responseStatus`** **(`SUCCESS`** **or `DENIED`) and the `authenticationId`** **value.

If this status is not received after 10 seconds, you can make a `POST` request to the `/authentications/{authentication-id}` endpoint. If the status has not been received and your attempt to call the `/authentications/{authentication-id}` endpoint is made before 10 seconds has elapsed, the API will return the following error: `httpStatus`**:**`400`** **`responseStatus`**:**`ERROR`** **`responseCode`**:**`DATA_COLLECTION_IN_PROGRESS`. If this error is received, wait the remainder of the 10 seconds before posting again.

The request to the `/authentications/{authentication-id}` endpoint allows you to provide the remaining required data for the 3DS process. Here is a request with minimum required fields:

**HTTP method**: `POST`
 **Endpoint**: `/authentications/{authentication-id}`

```json
{
    "channelType": "BROWSER",
    "threeDSRequestorAuthenticationInfo": {
        "authenticationPurpose": "MAINTAIN_CARD"
    },
    "threeDSPurchaseInfo": {
        "purchaseDate": "2023-08-21T15:12:12Z",
        "threeDomainSecureTransactionType": "GOODS_SERVICES"
    },
    "messageType": "NON_PAYMENT_AUTHENTICATION",
    "threeDSChallengeMerchantNotificationUrl": "https://www.example.com",
    "browserInfo": {
        "browserAcceptHeader": "application/json",
        "deviceIPAddress": "123.456.7.89",
        "browserLanguage": "en",
        "browserColorDepth": "8",
        "browserScreenHeight": "1",
        "browserScreenWidth": "1",
        "deviceLocalTimeZone": 1,
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
        "challengeWindowSize": "FULL_SCREEN",
        "javaEnabled": true,
        "javaScriptEnabled": true
    }
}
```

> The **threeDSChallengeMerchantNotificationUrl** should be the same URL the cardholder is on when the 3DS flow gets initiated. The URL will be used when a challenge is required to:
> 
> 
> - Send a postback to that URL.
> 
> - Redirect the cardholder back to/from the challenge.
> 
> While **threeDSChallengeMerchantNotificationUrl** is not a required field, card holders will get stranded in the flow if this field is not provided and the issuer requires a challenge.
> 
> The response and your next steps will depend on whether the authentication was [frictionless](/docs/commerce/optimization-protection/capabilities/3-d-secure/index#frictionless-authentications) or [challenge](/docs/commerce/optimization-protection/capabilities/3-d-secure/index#challenge-authentications).
> 

### Frictionless authentication results

If the issuer has performed a frictionless authentication, the API response will contain the full authentication results, including the electronic commerce indicator (ECI) in the threeDomainSecureCompletion.`electronicCommerceIndicator` value, and the authentication cryptogram in the threeDomainSecureCompletion.`threeDSAuthenticationValue` value. For additional information on using the `authenticationId` to simplify the completion of a payment, refer to the [Process the Payment](/docs/commerce/optimization-protection/capabilities/3-d-secure/how-to/request-a-3ds-auth#process-the-payment-coming-soon) section below.

## Launch the issuer challenge screen

If the issuer is requiring a cardholder challenge,  the authenticationResults.threeDomainSecureChallenge.`threeDSTransactionStatus` will contain a "C" value. The challenge is completed by rendering a hidden HTML iframe in the cardholder’s browser to post a form with the value of the following fields from the response to your `/authentications/{authentication-id}` request:

- authenticationResult.threeDomainSecureChallenge.threeDSChallengeRequest

- authenticationResult.threeDomainSecureChallenge.threeDSAcsUrl

```
<form name="frm" method="POST" action="{threeDSAcsUrl"> 
<input type="hidden" name="{threeDSChallengeData}" value=”{threeDSChallengeRequest}"> 
</form>
```

This will launch the challenge window provided by the cardholder’s issuer. The cardholder completes the challenge based on the issuing bank’s criteria. If the cardholder does not complete the challenge within ten minutes, the transaction will be considered abandoned and the status will be set to `ERROR`. If the cardholder completes the challenge, the authentication results will be provided.

## Listen for the "post back" after the authentication is complete

After the authentication process is complete, the [Online Payments API](/docs/commerce/online-payments/index) will “post back” to the `threeDSChallengeMerchantNotificationUrl` attribute provided in the `/authentications/{authentication-id}` request. The “post back” will include the `authenticationId` and `responseStatus` (`SUCCESS`, `ERROR`, or `DENIED`) to identify status of the authentication.

## Get the authentication results

To get the details associated with the authentication, perform a `GET` call to the `/authentications` endpoint using the `authenticationId` of the authentication.

## Process the payment (coming soon)

The `authenticationId` can be used to simplify including authentication results in a subsequent payment or verification via the [Online Payments API](/docs/commerce/online-payments/index) on the Commerce platform.

## Related

[3DS API](/docs/commerce/optimization-protection/capabilities/3-d-secure/index)
 [3DS API error codes](/api/commerce/optimization-protection/3-d-secure/error-codes)
 [3DS API specification](/api/commerce/optimization-protection/3-d-secure/3-d-secure)
 [Online Payments API](/docs/commerce/online-payments/index)
 [Online Payments API error codes](/api/commerce/online-payments/online-payments/error-codes)
 [Online Payments API specification](/api/commerce/online-payments/online-payments/online-payments)