online payments

3D Secure

3-D Secure (3DS) is an authentication protocol that allows merchants to request that the card issuer 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.

Tip

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 3D Secure works

Your consumer places an order on your website.
If you determine that the purchase warrants an authentication, initiate a 3DS authentication by making an API call to your 3DS authentication provider. Reasons for this may 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.
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:
1. Frictionless — The issuer completes the authentication using only information from the authentication API call and device information from the browser.
2. Challenge — The issuer prompts the cardholder to provide additional information to complete the authentication.
The issuer returns the authentication result to you via your 3DS authentication provider.
You include the authentication result in the purchase authorization to the card brands to complete the 3DS process.

Specific regions and regulations require 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.

Tip

To receive benefits associated with the payment brands, you should provide the information listed below in authorization processing after authentication.

SCA exemption

EU merchants may request a strong customer authentication (SCA) exemption to avoid passing 3DS. To request an SCA exemption, populate the 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 Payment Services Directive (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 transaction is 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 payment methods per exemption reason
Exemption reason	Eligible card payment method
TRUSTED_MERCHANT	Visa
SECURE_CORPORATE_PAYMENT	Visa, Mastercard (MC), International Maestro (IM), and American Express (AMEX)
TRANSACTION_RISK_ANALYSIS	Visa, MC, and IM
LOW_VALUE_PAYMENT	Visa, MC, and IM
MERCHANT_INITIATED_TRANSACTION	MC and IM
RECURRING_PAYMENT	MC and IM
SCA_DELEGATION	Visa, MC, and IM

3DS support

3DS is supported in the Online Payments API by allowing pass-through of 3DS values from an independent authentication provider or by using J.P. Morgan to orchestrate the browser flow.

Pass-through 3DS

Pass-through 3DS is used if you are using an independent 3DS authentication provider. With pass-through 3DS, you will perform the full authentication flow via the provider, and then use the results of the authentication in the authorization.

Specific values are provided to the merchant in the 3DS authentication response. These values must be included in the payment authorization request that is sent to J.P. Morgan. It is important to map these fields to the appropriate J.P. Morgan API fields without altering the field values.

authenticationValue — 3DS Base64 cryptogram obtained prior to payment request.
authenticationTransactionId — The directory server transaction ID.
threeDSProgramProtocol — Value based on the version of 3DS used to complete the authentication.
electronicCommerceIndicator — Indicates the outcome of the authentication. Sample electronicCommerceIndicator values are provided in the following table:

Tip

All values are located in paymentMethodType.card.authentication.

Applicable 3DS values for electronic commerce indicator (ECI)
Type	Visa	Mastercard	American Express	Discover/Diners	Japan Credit Bureau	UnionPay
Fully-authenticated 3DS transaction	05	01	05	00	05	05
Attempted authenticated 3DS transaction	06	02	06	07	06	06
Not authenticated	07	00	07	07	07	07

When processing recurring or non-authenticated transactions, J.P. Morgan populates the correct e-commerce value in the payment authorization.

Tip

If performing a network token transaction with 3DS and multiple ECIs are returned in the network token authentication response, use the value returned from the 3DS authentication.

Orchestrated 3DS

Orchestrated 3DS leverages J.P. Morgan’s own 3DS authentication server to perform authentication as part of the payment authorization request. The orchestrated 3DS Online Payments API requirements are as follows:

HTTP method: POST
Endpoints: /payments and /verifications
API field: "authenticationReturnUrl": "https://merchantreturnurl.com"

Tip

If the return URL is not provided, J.P. Morgan will not attempt 3DS orchestration and will proceed directly with authorization.

Required fields for orchestrated 3DS
Fields	/payments endpoint	/verifications endpoint	Required for 3DS
accountHolder firstName lastName billingAddress line1 line2 city state postalCode	Y	Y	Y
accountHolder referenceId consumerIdCreationDate phone countryCode phoneNumber	Y	Y
Accountholder shipTo line1 line2 city state postalCode	Y
browserInfo browserAcceptHeader deviceIPAddress browserLanguage browserColorDepth browserScreenHeight browserScreenWidth deviceLocalTimeZone browserUserAgent challengeWindowSize javaEnabled javaScriptEnabled	Y	Y	Y
paymentAuthenticationRequest authenticationReturnUrl	Y	Y	Y
paymentAuthenticationRequest authenticationSupportUrl accountType	Y	Y
paymentAuthenticationRequest threeDSAccountAdditionalInfo consumerAccountCreateLength consumerAccountCreateTimestamp consumerAccountUpdateLength consumerAccountUpdateTimestamp consumerAccountPasswordUpdateTimestamp consumerAccountPasswordChangeLength consumerAccountShippingAddressLength consumerAccountFirstShippingDate consumerAccountSuspiciousActivityIndicator consumerAccountShipNameIdenticalIndicator consumerAccountAddressIdenticalIndicator consumerPaymentAccountLength consumerPaymentAccountEnrollmentDate consumerAccount24HoursAddCardCount twentyFourHoursTransactionCount previousYearTransactionCount sixMonthTransactionCount	Y	Y
threeDSPurchaseInfo purchaseDate	Y	Y	Y
threeDSPurchaseInfo recurringAuthorizationDayCount threeDomainSecureTransactionType	Y	Y
threeDSRequestorPriorAuthenticationInfo priorReferenceID authenticationMethod authenticationTimestamp	Y	Y
threeDSRequestorAuthenticationInfo authenticationPurpose	Y	Y	Y
threeDSRequestorAuthenticationInfo threeDSAuthenticationTimestamp threeDSAuthenticationData threeDSChallengeType requestorAuthenticationMethod	Y	Y
threeDSPurchaseRisk shipmentType deliveryTimeframe orderEmailAddress productRepurchaseIndicator productAvailabilityCode preOrderDate purchasedPrepaidCardTotalAmount purchasedPrepaidCardCount prepaidCardCurrency	Y	Y
threeDSMessageExtensions messageExtensionId messageExtensionName messageExtensionCriticality messageExtensionData	Y	Y

Presenting orchestrated 3DS

Step 1: Begin orchestrated authentication

The Online Payments APIs automatically launche the authentication process by enabling the browser to create a frame targeted to the authenticationOrchestrationUrl attribute.

The supported dimensions displayed in the cardholder's browser are:

250 x 400
390 x 400
500 x 600
600 x 400

The following is an HTML code sample for creating the iframe:

Plaintext

<!DOCTYPE html> 
 <html lang="en"> 
 <head> 
     <meta charset="UTF-8"> 
     <meta name="viewport" content="width=device-width, initial-scale=1.0"> 
     <link rel="stylesheet" href="styles.css"> 
     <title>Merchant Site</title> 
 </head> 
 <body> 
     <iframe  
         id="hiddenIframe"  
         frameborder="0"  
         style=" 
             display: none;  
             width: 800px; 
             height: 600px;"  
         name="hiddenIframe"> 
     </iframe> 
     <script src="../orchestration.js"></script> 
 </body> 
 </html>

After calling the Authorizations API, use the orchestrationFormSubmit function to populate the iframe using the orchestration URL data from the authorization response data.

Plaintext

// orchestration.js
const iframeRef = document.getElementById("hiddenIframe"); 

// Triggers orchestration in your front end application 
function orchestrationFormSubmit 
(iframeRef, orchestrationUrlFromCheckoutResponse) { 
const form = document.createElement("form"); 
form.action = orchestrationUrlFromCheckoutResponse 

// 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: Receive the "post back" once the authentication is complete

Once the authentication process is complete, the Online Payments APIs will “post back” to the paymentAuthenticationRequest.authenticationReturnUrl attribute provided in the initial request. The “post back” will also include the paymentrequestId and a responseStatus (SUCCESS, ERROR, or DENIED) to identify status of the associated payment.

Step 3: Receive the additional payment details

To get the additional details associated with the payment, perform a GET call to the /payments or /verifications endpoint (depending on the endpoint to which the transaction was originally posted). If the authentication fails, the details of the authentication process can be found in the paymentAuthenticationResult attribute.

Cards
Authorize and capture a payment