Request a 3-D Secure (3DS) authentication

A 3DS authentication consists of the following steps:

Send a POST call to the /authentications endpoint.
Call the 3DS Method to collect data from the cardholder's browser.
Send a POST call to the /authentications/{authentication-id} endpoint.
Launch the issuer challenge screen (in instances when the issuer requires a challenge flow).
Listen for authentication results.
GET additional authentication details.
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:

Verifies whether the card issuer supports3DS for the card. If so, the responseCode field will be set to CREATED.
Finds the common 3DS version supported by the 3DS server, card brand network directory server, and issuer access control server (ACS).
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"
}

Note

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.

Plaintext

<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

Tip

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
    }
}

Note

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 or challenge.

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 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

Plaintext

<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 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 on the Commerce platform.

3DS API
3DS API error codes
3DS API specification
Online Payments API
Online Payments API error codes
Online Payments API specification