3DS Authentication

3D Secure (3DS) is an authentication protocol that allows you to request the card issuer to authenticate the cardholder prior to payment authorization or verification processing. A successful 3DS authentication (fully authenticated or attempted authentication) can:

Reduce fraudulent card transactions.
Shift the liability for certain fraud-related chargebacks to the card issuer.

How 3D Secure works

Your consumer places an order on your website.
You send the request to Checkout. For eligible merchants, Checkout will initiate a 3DS authentication request with the Payment Gateway.
The 3DS server passes the authentication request through to the card network directory server, and then to the card issuer.
The card issuer processes the authentication one of two ways:
- Frictionless — The issuer completes the authentication using only information from the authentication API call and device information from the browser.
- Challenge — The issuer prompts the cardholder to provide additional information to complete the authentication. In this case , the consumer is shown an authentication page of their bank’s website on the Checkout, where they’re prompted to enter a verification code sent to their phone or email and consumer completes the additional authentication step.
The issuer returns the authentication result to Checkout.
If authenticated successfully, Checkout will submit the payment authorization with the required 3DS authentication details to complete the order.

Orchestrated 3DS Authentication

Orchestrated 3DS leverages J.P. Morgan’s own 3DS authentication server to perform authentication as part of the payment authorization request.

Note

Checkout automatically initiates 3DS for EU merchants that are entitled to the 3DS feature even if the required field is omitted, as mandated by PSD2 regulation.

The following table shows the required and optional fields to perform orchestrated 3DS authentication.

Required and optional fields for Orchestrated 3DS authentication
Field name	Parent object	Description	Required for 3DS? (Y/N)
paymentCardAuthenticationRequest	checkoutOptions	The authentication request data which will be sent to 3DS provider if the Shopper is using a card as the payment method. This message is used by SetupCheckoutIntent API and must be populated if you want (or must) use SCA for card transactions.	Y (for all Non-EU/UK merchants)
threeDSchallengeType	paymentCardAuthenticationRequest	Indicates whether a challenge is requested for this transaction. Possible values are: NO_PREFERENCE - This is the default value if no other value is specified. The issuer determines if the challenge will be presented or not. NO_CHALLENGE - The merchant is requesting a frictionless flow. CHALLENGE_REQUESTED - The merchant is requesting for a challenge flow in the Authentication flow. CHALLENGE_MANDATE - A challenge is required under regulations e.g., when adding a card on file or starting a new subscription. NO_CHALLENGE_TRA - The merchant is requesting a TRANSACTION_RISK_ANALYSIS(TRA) exemption in the Authentication flow. NO_CHALLENGE_DATA – The merchant is requesting for data-based exemption in the Authentication flow. NO_CHALLENGE_DA - the merchant has delegated authentication responsibility to a third-party wallet provider or to a merchant instead of 3DS and requesting for exemption. NO_CHALLENGE_TRUSTED - the merchant is a trusted merchant with the cardholder.
cardholderAccountHistory	paymentCardAuthenticationRequest	Additional information about the Cardholder’s Account provided by the 3DS Requestor.
accountCreateTimestamp	cardholderAccountHistory	Designates the hour, minute and second on a specific day when the record was created.
accountUpdateTimestamp	cardholderAccountHistory	Designates the hour, minute, and second on a specific day when the record was last modified.
cardFirstUsedDate	cardholderAccountHistory	Date that the payment account was enrolled in the Cardholder’s account with the 3DS Requestor. If this field is not set, then the Cardholder never used this card before and it' a guest checkout.
consumerAccount24HoursAddCardCount	cardholderAccountHistory	Enumerates the merchant reported number of card addition attempts as a payment method by the consumer in their consumer profile during the last 24 hours.
consumerAccountPasswordUpdateTimestamp	cardholderAccountHistory	Designates the hour, minute, and second on a specific day when the record was last modified.
last24HoursTransactionCount	cardholderAccountHistory	Enumerates the occurrences of any transaction within a given period.
lastYearTransactionCount	cardholderAccountHistory	Enumerates the occurrences of any transaction within a given period.
last6MonthsPurchaseCount	cardholderAccountHistory	The number of requested merchant-based purchase transactions for the cardholder over a specified time frame.
consumerAccountSuspiciousActivityIndicator	cardholderAccountHistory	Indicates the merchant has experienced suspicious activity (including previous fraud) on the consumer account. This is used for the assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
consumerAccountAddressIdenticalIndicator	cardholderAccountHistory	Indicates if the Cardholder billing address and shipping address are identical for this transaction.
consumerShippingAddressFirstUsageDate	cardholderAccountHistory	Designates the year, month and day when the shipping address for this consumer profile was first used for the delivery of a purchased product.
consumerShipToNameIdenticalIndicator	cardholderAccountHistory	Indicates the consumer's name on the account is identical to the shipping name used for this transaction.
purchaseInfo	paymentCardAuthenticationRequest	Purchase information.
lastPurchaseDate	purchaseInfo	Designates the year, month and day of the most recent purchase which occurred on the Cardholder account.
paymentFrequency	purchaseInfo	Minimum number of days between authorizations.
merchantFraudRiskAssessment	purchaseInfo	Merchant's assessment of the level of fraud risk for the specific authentication for both the Cardholder and the authentication being conducted.
shipmentType	merchantFraudRiskAssessment	Indicates shipping method chosen for the transaction.
deliveryTimeframe	merchantFraudRiskAssessment	Codifies the shipment period of time chosen by the consumer in the purchase transaction from the merchant as defined by the Three Domain Secure (3-D Secure or 3DS) cardholder authentication process. This is used for the assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
orderEmailAddress	merchantFraudRiskAssessment	A mail system that allows a party to send and receive messages electronically. An email address is composed of a local part and a domain part. The local part is unique to the individual while the domain or host name must meet specific standards required by the host that administers the email service.
productRepurchase	merchantFraudRiskAssessment	Whether the Cardholder is reordering previously purchased merchandise.
productPreorder	merchantFraudRiskAssessment	Whether Cardholder is placing an order for merchandise with a future availability or release date.
preorderAvailabilityDate	merchantFraudRiskAssessment	For a pre-ordered purchase, the expected date that the merchandise will be available.
requestorAuthenticationInfo	paymentCardAuthenticationRequest	Information about how the 3DS Requestor authenticated the Cardholder before or during the transaction.
requestorAuthenticationMethod	requestorAuthenticationInfo	Codifies how the Three Domain Secure (3-D Secure or 3DS) Requestor (merchant) authenticated the cardholder before or during the transaction.
threeDSAuthenticationTimestamp	requestorAuthenticationInfo	Designates the hour, minute and second in a specific day when the Three Domain Secure (3-D Secure or 3DS) Requestor (merchant) authenticated the cardholder before or during the transaction.
threeDSAuthenticationData	requestorAuthenticationInfo	Data that documents and supports a specific authentication process.
requestorPriorTransactionAuthenticationInfo	paymentCardAuthenticationRequest	Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.
acsTransactionId	requestorPriorTransactionAuthenticationInfo	A unique identifier for the Three Domain Secure (3-D Secure or 3DS) Requestor (merchant) authentication of the cardholder before or during the transaction.
requestorAuthenticationMethod	requestorPriorTransactionAuthenticationInfo	Codifies how the Three Domain Secure (3-D Secure or 3DS) Requestor (merchant) authenticated the cardholder before or during the transaction.
threeDSAuthenticationTimestamp	requestorPriorTransactionAuthenticationInfo	Designates the hour, minute and second on a specific day when the Three Domain Secure (3-D Secure or 3DS) Requestor (merchant) authenticated the cardholder before or during the transaction.
threeDSAuthenticationData	requestorPriorTransactionAuthenticationInfo	Data that documents and supports a specific authentication process.
SCAExemptionReason	paymentCardAuthenticationRequest	Indicates the justification why a transaction does not have to meet Strong Customer Authentication (SCA) requirements.
email	consumer	A mail system that allows a party to send and receive messages electronically. An email address is composed of a local part and a domain part. The local part is unique to the individual while the domain or host name must meet specific standards required by the host that administers the email service.

Utilize orchestrated 3DS by performing a POST call to the /checkout/intent endpoint with the necessary required fields populated.

HTTP method: POST

Endpoint: /checkout/intent

Scenario: 3DS authentication request is sent by adding paymentCardAuthenticationRequest to the request body under the checkoutOptions object.

Json

{
    "currencyCode": "USD",
    "merchantOrderNumber": "X1G5VZMxplIm1tRRcrC85o",
    "checkoutOptions": {
        "authorization": {
            "authorizationType": "AUTH_METHOD_CART_AMOUNT"
        },
        "capture": {
            "captureMethod": "CAPTURE_METHOD_NOW"
        },
        "paymentCardAuthenticationRequest": {
            "threeDSChallengeType": "CHALLENGE_TYPE_NO_CHALLENGE_REQUESTED",
            "cardholderAccountHistory": {
                "accountCreateTimestamp": "2023-06-04T11:55:20.021Z",
                "accountUpdateTimestamp": "2023-06-06T10:00:20.021Z",
                "cardFirstUsedDate": "2022-10-02T10:00:20.051Z",
                "consumerAccount24HoursAddCardCount": 1,
                "consumerAccountPasswordUpdateTimestamp": "2023-12-04T12:11:54.021Z",
                "last24HoursTransactionCount": 0,
                "lastYearTransactionCount": 10,
                "last6MonthsPurchaseCount": 5,
                "consumerAccountSuspiciousActivityIndicator": false,
                "consumerAccountAddressIdenticalIndicator": true,
                "consumerShippingAddressFirstUsageDate": "2023-12-06T12:11:54.021Z",
                "consumerShipToNameIdenticalIndicator": true
            },
            "purchaseInfo": {
                "lastPurchaseDate": "2023-12-06T12:11:54.021Z",
                "merchantFraudRiskAssessment": {
                    "shipmentType": "SHIPPING_METHOD_SHIP_TO_BILLING_ADDRESS",
                    "deliveryTimeframe": "DELIVERY_TYPE_SAME_DAY_SHIPPING",
                    "orderEmailAddress": "john.doe@gmail.com"
                }
            },
            "requestorAuthenticationInfo": {
                "requestorAuthenticationMethod": "REQUESTOR_AUTHENTICATION_METHOD_REQUESTOR_CRED",
                "threeDSAuthenticationTimestamp": "2023-12-06T16:31:54.021Z"
            },
            "requestorPriorTransactionAuthenticationInfo": {
                "requestorAuthenticationMethod": "PRIOR_AUTHENTICATION_METHOD_FRICTIONLESS_AUTHENTICATION_BY_ACS",
                "threeDSAuthenticationTimestamp": "2023-12-06T16:31:54.021Z"
            }
        }
    },
    "cart": {
        "totalTransactionAmount": 1000
    }
}

Response:

Json

{
    "checkoutSessionToken": "eyJraWQiOiJlYmRhNTZhOS1hZjMxLTQ3YzItYjE4OS01MWFjNmFiNWEwYjQiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJrc2kiOiJmYTBkOTI3OThlNTk1MmRkYWYxZTc0MjM2ZjNkM2M5NSIsIlJvbGUiOlsiVFJBTlNBQ1RJT05BTF9DSEVDS09VVF9TSE9QUEVSIl0sIm1vciI6IjEwMDI2ODExMzUiLCJvZCI6ImUwZTdjZTgwMmI2NWE1ZjIwYWNkZjZhYzhkNmUwZWNhY2FiMWE2MjBjY2M0NzY0M2UyNzRkN2FiNTMyODA5MGFhMjI5ZTdkOTBjNDRjZGQ4M2JmNjM5MzMxN2M3ODk0MGNjOGQ3OWQ4OWI1ZjY2NGQ1OTNmODcxYzJhMjBhMTEwIiwiaXNzIjoiY2hlY2tvdXQiLCJtaWQiOiJjZTBjMDY1Ny1lOTFiLTQ1ZDAtOWVmNS02ODU2NTM5NDIyMjg6NDUxMjA3Iiwib2lkIjoiMjNjODMyODItZTVjMi00M2VhLTk2MGItZjdiOGRiMDM2ODliIiwiZXhwIjoxNjgwMTMyMDYwLCJtc3IiOiIiLCJzcGkiOiJkYTk0MmIzZC0wNTgyLTQ1MTEtOTBkZS04ZDE5YWUzZWQxZjciLCJpYXQiOjE2ODAxMjQ4NjB9.YtcZK2o2_CAN7j3JjHhgyjZGxD_wcC7L0CI22mm_qfzH7HlBboMX7qahqOYauda5_P-4pPJuvoda46aqmEzUgTr2tScRwHo6lsD8_L-in5-7BD53LnxvsB_NS97zT6CjBSk4flsy-Cgw_PvvQMaTnl-E64nvmaBI7DK_1qzaqBNQxfZwot83Dk66m3I3E5M-8INBe-WyzVfr4ywyE03Db2IPN-_Vk2WWFoys46hNEuX2qIazki3-jFCnqD5DLejEtLJ2bpzrXK_O76_DOaF3i_pRvytyPmfs9C1tI5tsTAr4W6YFMlSaDaFvVg-sd9SqAbZddMRkSp2jrTR2J4d4HA",
    "redirectUrl": ""
}

SCA Exemption

In certain scenarios, you can request the payment to be exempted from Strong Customer Authentication (SCA). The cardholder’s bank will receive the authorization request requesting for an exemption, assess the risk level of the transaction, and ultimately decide whether to approve the exemption or if authentication is still necessary.

Step 1: Send the request to Checkout

Send the payment to Checkout with the field SCAExemptionReason populated with the applicable exemption type. Allowed values are :

SCA Exemption types and the card brands they apply to
SCA Exemption type	Description	Eligible card brands
SCA_EXEMPTION_LOW_VALUE_PAYMENT	Transactions are eligible for SCA exemption when the transaction amount is below the limit established by PSD2/RTS.	Visa, MasterCard , International Maestro
SCA_EXEMPTION_TRUSTED_MERCHANT	Transactions are eligible for SCA exemption when a merchant is allow listed by the cardholder.	Visa
SCA_EXEMPTION_TRANSACTION_RISK_ANALYSIS	Transactions are eligible for SCA exemption if transaction fraud rates are below established thresholds defined by Payment Services Directive (PSD2)/Regulatory Technical Standards (RTS).	Visa, MasterCard , International Maestro
SCA_EXEMPTION_SECURE_CORPORATE_PAYMENT	Secure corporate or business-to-business (B2B) payments over dedicated payment processes and protocols are exempted from SCA.	Visa, MasterCard , International Maestro , American Express
SCA_EXEMPTION_MERCHANT_INITIATED_TRANSACTION	Transactions processed within the merchant-initiated transaction (MIT) framework are exempt from SCA. The initial transaction must meet SCA requirements.	MasterCard , International Maestro
SCA_EXEMPTION_RECURRING_PAYMENT	Recurring transaction is eligible for SCA exemption. The initial transaction must meet SCA requirements.	MasterCard , International Maestro
SCA_EXEMPTION_DELEGATION	Transactions are eligible for SCA exemptions when an issuer has delegated authentication responsibility to a third-party wallet provider or to a merchant.	Visa, MasterCard , International Maestro

Step 2: Checkout will process the payment with the exemption

Checkout will process and send the payment to the card issuers with the exemption details as requested by you. The following scenarios can occur after this:

Issuer approves the payment with the SCA exemption: Payment authorization is approved.
Issuer soft declines the payment requesting for Authentication. In this scenario, Checkout will resubmit the transaction without the exemption.

The following is an example of a SCA Exemption request.

Method: POST

Endpoint: /checkout/intent

Scenario: Sending SCA Exemption request

Json

{
    "currencyCode": "USD",
    "merchantOrderNumber": "1006954249",
    "checkoutOptions": {
        "authorization": {
            "authorizationType": "AUTH_METHOD_CART_AMOUNT"
        },
        "capture": {
            "captureMethod": "CAPTURE_METHOD_NOW"
        },
        "consumerProfileOptions": {
            "isSaveConsumerProfile": "true"
        },
        "paymentCardAuthenticationRequest": {
            "threeDSChallengeType": "CHALLENGE_TYPE_NO_PREFERENCE",
            "cardholderAccountHistory": {
                "accountCreateTimestamp": {
                    "seconds": 1706558896
                },
                "accountUpdateTimestamp": {
                    "seconds": 1706558896
                },
                "cardFirstUsedDate": {
                    "seconds": 10
                },
                "consumerAccount24HoursAddCardCount": 1,
                "consumerAccountPasswordUpdateTimestamp": {
                    "seconds": 10
                },
                "last24HoursTransactionCount": 1,
                "lastYearTransactionCount": 10,
                "last6MonthsPurchaseCount": 5,
                "consumerAccountSuspiciousActivityIndicator": false,
                "consumerAccountAddressIdenticalIndicator": true,
                "consumerShippingAddressFirstUsageDate": {
                    "seconds": 1699922241
                },
                "consumerShipToNameIdenticalIndicator": true
            },
            "purchaseInfo": {
                "lastPurchaseDate": {
                    "seconds": 1699922241
                },
                "paymentFrequency": "10",
                "merchantFraudRiskAssessment": {
                    "shipmentType": "SHIPPING_METHOD_SHIP_TO_BILLING_ADDRESS",
                    "deliveryTimeframe": "DELIVERY_TYPE_SAME_DAY_SHIPPING",
                    "orderEmailAddress": "user@email.com",
                    "productRepurchase": false,
                    "productPreorder": false
                }
            },
            "requestorAuthenticationInfo": {
                "requestorAuthenticationMethod": "REQUESTOR_AUTHENTICATION_METHOD_REQUESTOR_CRED",
                "threeDSAuthenticationTimestamp": {
                    "seconds": 1699922241
                }
            },
            "requestorPriorTransactionAuthenticationInfo": {
                "acsTransactionId": "450083445",
                "requestorAuthenticationMethod": "PRIOR_AUTHENTICATION_METHOD_FRICTIONLESS_AUTHENTICATION_BY_ACS",
                "threeDSAuthenticationTimestamp": {
                    "seconds": 1699922241
                }
            },
            "SCAExemptionReason": "SCA_EXEMPTION_LOW_VALUE_PAYMENT"
        }
    }
}

Retrieve additional details in the payment notification

Get additional details associated with the payment by performing a GET call to the /checkout/notifications endpoint. The 3DS details are available in the orderNotification object.

HTTP method: GET

Endpoint: /checkout/notifications

Scenario: Retrieving a payment notification

Json

{
    "messages": [
        {
            "messageInfo": {
                "messageId": "4e35187c-600d-4578-a89a-f32f699b1cdd",
                "receiptHandle": ""
            },
            "orderNotification": {
                "checkoutIntent": "CHECKOUT_INTENT_AUTH_AND_CAPTURE",
                "threeDomainSecureTransaction": {
                    "threeDSTransactionStatus": "Y",
                    "authenticationStatusReasonText": "Authentication Successful",
                    "challengeAuthenticationMethod": "SMS_OTP",
                    "challengeAuthenticationType": "DYNAMIC"
                }
            },
            "createdAt": "2024-01-19T20:37:26.403168Z"
        }
    ]
}

The following table lists the details of the fields and possible values of a 3DS notifications response:

3DS notification's response fields, valid values, and their descriptions
Field name	Description
threeDSTransactionStatus	The status of the 3DS transaction. Y - Authentication was successful. N - Authentication was not successful. Transaction was denied. U - Authentication could not be performed due to technical or other problems. C - A challenge is required to authenticate the cardholder. R - Authentication was rejected. A - An attempt to process the authentication was made but it was not successful. A proof of attempted authentication. D - Decoupled authentication. A challenge is required to authenticate. I - Informational Only. The 3DS requestor's challenge preference was acknowledged.
authenticationStatusReasonText	A long explanation of the authentication status.
challengeAuthenticationMethod	Information about how the 3DS requestor authenticated the cardholder for the challenge request. STATIC_PASSCODE SMS_OTP KEY_FOB APP_OPT OPT_OTHER KBA OOB_BIOMETRICS OOB_LOGIN OOB_OTHER OTHER PUSH_CONFIRMATION
challengeAuthenticationType	The category of authentication request the issuer will use to challenge the cardholder in the 3DS authentication process. STATIC DYNAMIC OOB DECOUPLED