# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # 3-D Secure 3-D Secure (3DS) is an authentication service that allows you to verify the identity of your cardholder prior to completing the payment authorization or verification. A successful authentication enables you to: - Reduce fraudulent card transactions - Shift the cost liability of fraud-related chargebacks to the card issuer - Help you to meet EU/U.K. Payment Services Directive 2 (PSD2) Strong Customer Authentication (SCA) requirements ## Who uses 3DS authentication? Leverage 3DS authentication if you have consumers in Europe or other markets where 3DS is required, or if you want to reduce your card payments risk liability. We support the following 3DS options on our Commerce platform: - [Orchestrated 3DS](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure#orchestrated-3ds) — J.P. Morgan handles the 3DS authentication flow for you as part of your card payment transaction process. - [3DS API](/docs/commerce/optimization-protection/capabilities/3-d-secure/index) — Manage the entire 3DS workflow yourself separate from the card payment process. - [Pass-through 3DS](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure#passthrough-3ds) — Pass-through 3DS values obtained from an independent 3DS provider in your payment transactions to J.P. Morgan. > 3DS is supported in the [Online Payments API](/docs/commerce/online-payments/index) by using J.P. Morgan to [orchestrate the authentication flow](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure#orchestrated-3ds), or by [allowing pass-through of 3DS values](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure#passthrough-3ds) from an independent authentication provider. Additionally, J.P. Morgan’s client managed [3DS API](/docs/commerce/optimization-protection/capabilities/3-d-secure/index) can be accessed and used independently from the Online Payments API for more control over the authentication process. > > To begin authenticating cardholders using 3DS, you must first choose and integrate with a 3DS authentication provider. This can be J.P. Morgan or a third-party authentication vendor. > > ## How 3DS works ![3-D Secure Process Flow](/api/download/en/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure-cfs/3DS_Procflow.png?type=image) 1. Your consumer places an order on your website. 2. If you determine that the purchase warrants authentication, initiate a 3DS authentication with your 3DS authentication provider. Reasons a transaction warrants authentication include: 1. The authentication is mandated by a regulation like PSD2 in Europe. 2. The cardholder is a new consumer with whom you have no prior business relationship. 3. The item being purchased is a common target for fraudulent purchases. 3. Your 3DS provider passes the authentication request through to the card issuer. 4. The card issuer processes the authentication one of two ways: 1. [Frictionless](/docs/commerce/optimization-protection/capabilities/3-d-secure/index#frictionless-authentications) — The issuer completes the authentication using only information from the authentication API call and device information from the browser. 2. [Challenge](/docs/commerce/optimization-protection/capabilities/3-d-secure/index#challenge-authentications) — The issuer prompts the cardholder to provide additional information to complete the authentication. 5. The issuer returns the authentication results to you via your 3DS authentication provider. 6. If you decide to process a transaction using the [Online Payments API](/docs/commerce/online-payments/index) for your consumer's order based on a successful authentication response, include the authentication result details in your /payments or /verifications request. > Including the successful 3DS authentication results in your authorization transaction shifts the liability for a fraud-related chargeback to the issuer, a payment brand benefit. > Specific regions (such as EU, U.K., India, and Australia) have regulations requiring e-commerce merchants to utilize authentication protocols, such as 3DS. Payment network mandates also provide guidance on how and when to utilize 3DS with their specific card products. You are ultimately responsible for knowing whether 3DS is applicable to you. ## Strong Customer Authentication (SCA) exemption EU merchants request an SCA exemption to avoid performing 3DS authentication and passing 3DS authentication results in the purchase authorization. To request an SCA exemption, populate the paymentMethodType.card.authentication.`SCAExemptionReason` field with one of the following exemption reasons: - TRUSTED_MERCHANT — Transactions are eligible for SCA exemption when a merchant is "allow" listed by the cardholder. - SECURE_CORPORATE_PAYMENT — Secure corporate or business-to-business (B2B) payments over dedicated payment processes and protocols are exempted from SCA. - TRANSACTION_RISK_ANALYSIS — Transactions are eligible for SCA exemption if transaction fraud rates are below established thresholds defined by PSD2/Regulatory Technical Standards (RTS). - LOW_VALUE_PAYMENT — Transactions are eligible for SCA exemption when the transaction amount is below the limit established by PSD2/RTS. - MERCHANT_INITIATED_TRANSACTION — Transactions processed within the merchant-initiated transaction (MIT) framework are exempt from SCA. The initial transaction must meet SCA requirements. - RECURRING_PAYMENT — Recurring transactions are eligible for SCA exemption. The initial transaction must meet SCA requirements. - SCA_DELEGATION — Transactions are eligible for SCA exemptions when an issuer has delegated authentication responsibility to a third-party wallet provider or to a merchant. The following table lists permitted card payment methods per exemption reason: **Permitted card brands per exemption reason** | Exemption reason | Eligible card brands | | --- | --- | | TRUSTED_MERCHANT | Visa | | SECURE_CORPORATE_PAYMENT | Visa, Mastercard, International Maestro, and American Express | | TRANSACTION_RISK_ANALYSIS | Visa, Mastercard, and International Maestro | | LOW_VALUE_PAYMENT | Visa, Mastercard, and International Maestro | | MERCHANT_INITIATED_TRANSACTION | Mastercard and International Maestro | | RECURRING_PAYMENT | Mastercard and International Maestro | | SCA_DELEGATION | Visa, Mastercard, and International Maestro | ## Orchestrated 3DS Orchestrated 3DS leverages J.P. Morgan’s own 3DS authentication server to perform authentication as part of the payment authorization or verification request. ![Orchestration challenge flow](/api/download/en/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure-cfs/OrchestrationChallengeFlowRevised2.png?type=image) The orchestrated 3DS Online Payments API requirements, for payments and verifications respectively, are as follows: - HTTP method: POST - Endpoints: /payments and /verifications - API field: "paymentMethodType.card.AuthenticationRequest.authenticationReturnUrl": "https://merchantreturnurl.com" > If you do not provide a return URL, J.P. Morgan does not attempt 3DS orchestration and, instead, proceeds directly to authorization. > ### Required fields by payment brand The following fields are required for orchestrated 3DS sorted by card brand requirement. **Required fields for orchestrated 3DS** | Field | Required by | | --- | --- | | paymentMethodType.card.paymentAuthenticationRequest.authenticationReturnUrl | All card brands | | paymentMethodType.card.paymentAuthenticationRequest.threeDSRequestorAuthenticationInfo.authenticationPurpose | All card brands | | paymentMethodType.card.paymentAuthenticationRequest.threeDSRequestorAuthenticationInfo.authenticationUseCase | Cartes Baincaires only | | paymentMethodType.card.paymentAuthenticationRequest.threeDSPurchaseInfo.purchaseDate | All card brands | | paymentMethodType.card.paymentAuthenticationRequest.threeDSPurchaseInfo.threeDomainSecureTransactionType | All card brands | | paymentMethodType.card.paymentAuthenticationRequest.threeDSPurchaseInfo.purchasedItemCount | Cartes Baincaires only | | paymentMethodType.card.paymentAuthenticationRequest.threeDSPurchaseRisk.requestorEstimatedTransactionFraudRiskScore | Cartes Baincaires only | | paymentMethodType.card.verificationAuthenticationRequest.authenticationReturnUrl | All card brands | | paymentMethodType.card.verificationAuthenticationRequest.threeDSRequestorAuthenticationInfo.authenticationPurpose | All card brands | | paymentMethodType.card.verificationAuthenticationRequest.threeDSRequestorAuthenticationInfo.authenticationUseCase | Cartes Baincaires only | | paymentMethodType.card.verificationAuthenticationRequest.threeDSPurchaseInfo.purchaseDate | All card brands | | paymentMethodType.card.verificationAuthenticationRequest.threeDSPurchaseInfo.threeDomainSecureTransactionType | All card brands | | paymentMethodType.card.verificationAuthenticationRequest.threeDSPurchaseInfo.purchasedItemCount | Cartes Baincaires only | | paymentMethodType.card.verificationAuthenticationRequest.threeDSPurchaseRisk.requestorEstimatedTransactionFraudRiskScore | Cartes Baincaires only | | accountHolder.firstName | All card brands unless restricted by market or regional mandate | | accountHolder.lastName | All card brands unless restricted by market or regional mandate | | accountHolder.email | All card brands unless restricted by market or regional mandate | | accountHolder.billingAddress.line1 | All card brands unless restricted by market or regional mandate | | accountHolder.billingAddress.city | All card brands unless restricted by market or regional mandate | | accountHolder.billingAddress.postalCode | All card brands unless restricted by market or regional mandate | | accountHolder.billingAddress.countryCode | All card brands unless restricted by market or regional mandate | | accountHolder.phone.phoneNumber | All card brands unless restricted by market or regional mandate | | browserInfo.browserAcceptHeader | All card brands | | browserInfo.deviceIPAddress | All card brands | | browserInfo.browserLanguage | All card brands | | browserInfo.browserColorDepth | All card brands | | browserInfo.browserScreenHeight | All card brands | | browserInfo.browserScreenWidth | All card brands | | browserInfo.deviceLocalTimeZone | All card brands | | browserInfo.browserUserAgent | All card brands | | browserInfo.challengeWindowSize | All card brands | | browserInfo.javaEnabled | All card brands | | browserInfo.javaScriptEnabled | All card brands | > Cartes Bancaires extends the 3DS standard by adding values to the authentication message extensions. The API simplifies that by adding new API fields that will populate the message extensions on your behalf. In the API, `authenticationUseCase` populates **CB-USECASE**, `purchasedItemCount` populates **CB-ITEMSNB**, and `requestorEstimatedTransactionFraudRiskScore` populates **CB-SCORE_MERCHANT**. > ### Initiating orchestrated 3DS **Step 1: Set up HTML ** The Online Payments API enables the orchestrated authentication process by allowing the browser to create a frame targeted to the `authenticationOrchestrationUrl` attribute.. The following is an HTML sample for creating the iframe: ``` Merchant Site ``` Implement the following function to be called in a later step: ```javascript // orchestration.js const iframeRef = document.getElementById("hiddenIframe"); // Triggers orchestration in your front end application function orchestrationFormSubmit (iframeRef, orchestrationUrlFromResponse) { const form = document.createElement("form"); form.action = orchestrationUrlFromResponse // Takes the query parameters from the orchestrationUrl and applies them to the javascript form that will be submitted const signedUrl = new URL(form.action) signedUrl.searchParams.forEach(function(value, key) { const signatureInformation = document.createElement("input") signatureInformation.name = key; signatureInformation.value = value; form.appendChild(signatureInformation); }) form.method = "GET"; form.target = iframeRef.name document.body.appendChild(form); form.submit(); document.body.removeChild(form); } ``` **Step 2: Call Online Payments API** Make your `/payments` or `/verifications` request as normal, including the appropriate 3DS fields. Be sure to collect browser info prior to making the request. Use the following example for a `/payments` request: ```json { "amount": 14500, "currency": "USD", "paymentMethodType": { "card": { "accountNumber": "4112344112344113", "expiry": { "month": 5, "year": 2040 }, "paymentAuthenticationRequest": { "authenticationReturnUrl": "merchantCheckoutPage.com", "threeDSRequestorAuthenticationInfo": { "authenticationPurpose": "PAYMENT_TRANSACTION" }, "threeDSPurchaseInfo": { "purchaseDate": "2028-10-31T17:07:14.91Z", "threeDomainSecureTransactionType": "GOODS_SERVICES" } } } }, "accountHolder": { "firstName": "John", "lastName": "Doe", "email": "example@example.com", "billingAddress": { "line1": "1234 Main Street", "city": "New York", "postalCode": "10111" }, "phone": { "countryCode": "1", "phoneNumber": "1234567890" } }, "merchant": { "merchantSoftware": { "companyName": "John's Gym", "productName": "Cart" } }, "browserInfo": { "browserAcceptHeader": "application/json", "deviceIPAddress": "192.168.1.11", "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 } } ``` **Step 3: Call the orchestrationFormSubmit function** Use the AuthenticationResult.`authenticationOrchestrationUrl` from the response to set the `orchestrationUrlFromResponse` variable in your JS. After the `orchestrationUrlFromResponse`** **is set, call `orchestrationFormSubmit`. At this point, J.P. Morgan’s 3DS server performs authentication, and the Online Payments API automatically creates the payment or verification. **Step 4: Listen for the POST HTTP request** After the authentication process completes, the Online Payments APIs sends a `POST` HTTP request (also called the "postback") to the URL you sent in AuthenticationRequest.`authenticationReturnUrl` on your `/payments` or `/verifications` request. The postback call includes the `paymentrequestId` and a `responseStatus` (`SUCCESS`, `ERROR`, or `DENIED`) of the associated payment or verification. **Step 5: Request additional payment details** To get the additional details associated with the transaction, perform a `GET` call to the `/payments` or `/verifications` endpoint (depending on the endpoint to which the transaction was originally posted). Authentication details, including any errors, are provided in the `AuthenticationResult` attribute. ## Pass-through 3DS We support pass-through 3DS if you use an independent 3DS authentication provider. With pass-through 3DS, you perform the full authentication flow via your authentication provider and include the 3DS results in the Online Payments API transaction. The 3DS authentication response from your provider contains specific values. You must map these fields to the appropriate Online Payment API request fields without altering the field values. Within the paymentMethodType.card.`authentication` object, populate the following fields with pass-through 3DS authentication data: - electronicCommerceIndicator - The outcome of the authentication. - threeDS.authenticationValue - 3DS Base64 cryptogram obtained prior to payment request. - threeDS.authenticationTransactionId - The directory server transaction ID is used for Mastercard and Cartes Bancaires, while the XID field is used for Visa. - threeDS.threeDSProgramProtocol - Value based on the version of 3DS used to complete the authentication. To learn more about the pass-through 3DS authentication fields required for Cartes Bancaires, refer to [Required fields by payment brand](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/3d-secure#required-fields-by-payment-brand-1). ### Electronic Commerce Indicator (ECI) values for 3DS Your 3DS provider sends you the ECI value, which you then pass in your Online Payments API request. "Fully authenticated" means the issuer has successfully authenticated the cardholder. "Attempted authentication" means the issuer did not attempt to authenticate, but the card brand did and was successful. "Not authenticated" means the authentication failed. **ECI values for 3DS** | Type | Visa | Mastercard/International Maestro | American Express | Discover/Diners | Japan Credit Bureau | UnionPay | | --- | --- | --- | --- | --- | --- | --- | | Fully-authenticated | 05 | 02 | 05 | 05 | 05 | 05 | | Attempted authenticated | 06 | 01 | 06 | 06 | 06 | 06 | | Not authenticated | 07 | 00 | 07 | 07 | 07 | 07 | > If you perform a network token transaction with 3DS and your authentication provider returns multiple ECI values, use the value specific to 3DS authentication. > ### Required fields by payment brand **Required fields by payment brand** | Field | Visa | Mastercard | American Express | Discover | Cartes Bancaires | | --- | --- | --- | --- | --- | --- | | electronicCommerceIndicator | Y | Y | Y | Y | Y | | authenticationValue | Y | Y | Y | Y | Y | | authenticationTransactionId | Y | Y | | | Y | | threeDSProgramProtocol | | Y | | | Y | | Version2.threeDSTransactionStatus | | | | | Y | | Version2.threeDSTransactionStatusReasonCode | | | | | Y (Not required if threeDSTransactionStatus = Y) | | authenticationValueCalculationMethod | | | | | Y | | threeDSChallengeType | | | | | Y | | issuerAssignedAuthenticationExemptionEncoded | | | | | Y | | threeDomainSecureAuthenticationMethodCode | | | | | Y | | issuerAssignedAuthenticationFraudScore | | | | | Y | Cartes Bancaires extends the 3DS standard by adding values to the authentication message extensions to the 3-DS API response. Those message extension values are provided in the authorization in the following fields: **3DS message extension values for Cartes Bancaires** | Message extension value | Payments API field | | --- | --- | | CB-AVALGO | authenticationValueCalculationMethod | | CB-EXEMPTION | issuerAssignedAuthenticationExemptionEncoded | | CB-SCORE | issuerAssignedAuthenticationFraudScore | ### Processing recurring and subscription transactions for Cartes Bancaires Cartes Bancaires has special requirements for processing recurring and subscription transactions, requiring a number of values from the 3-DS authentication on the initial customer transaction, to be sent in every subsequent recurring authorization for that subscription. Retain these values from the original authentication for the duration of the subscription. The payments API has an object that contains these values under paymentMethodType.card.athentication.threeDS.`initialThreeDSAuthenticationResults`. These fields are: - initialThreeDSProgramProtocol - initialThreeDSAuthenticationTimestamp - initialThreeDSAuthenticationAmount - initialThreeDSAuthenticationTransactionId - initialThreeDSAuthenticationMethodCode - initialThreeDSChallengeType - initialIssuerAssignedAuthenticationFraudScore Refer to the following example of a payment with pass-through 3DS: ```json { "amount": 14500, "currency": "USD", "paymentMethodType": { "card": { "accountNumber": "4110144110144115", "expiry": { "month": 5, "year": 2040 }, "authentication": { "electronicCommerceIndicator": "05", "threeDS": { "authenticationValue": "AABAIcJIo5DIzAgVAkiAAAAAAA=", "authenticationTransactionId": "01ade6ae340005c681c3a1890418", "threeDSProgramProtocol": 2 } } } }, "accountHolder": { "firstName": "John", "lastName": "Doe", "email": "example@example.com", "billingAddress": { "line1": "1234 Main Street", "city": "New York", "postalCode": "10111" }, "phone": { "countryCode": "1", "phoneNumber": "1234567890" } }, "merchant": { "merchantSoftware": { "companyName": "John's Gym", "productName": "Cart" } } } ``` ## Related [3DS API](/docs/commerce/optimization-protection/capabilities/3-d-secure/index) [3DS API response codes](/api/commerce/optimization-protection/3-d-secure/error-codes) [3DS API specification](/api/commerce/optimization-protection/3-d-secure/3-d-secure) [Authorize and capture a payment](/docs/commerce/online-payments/capabilities/online-payments/how-to/auth-and-capture-payment) [Cards](/docs/commerce/online-payments/capabilities/online-payments/payment-methods/cards/index) [Online payments response codes](/api/commerce/online-payments/online-payments/error-codes) [Online Payments API specification](/api/commerce/online-payments/online-payments/online-payments) [Request a 3DS authentication](/docs/commerce/optimization-protection/capabilities/3-d-secure/how-to/request-a-3ds-auth)