3D Secure 2 (EMV 3D Secure)

3D Secure 2 (EMV 3D Secure)
Under no circumstances should merchants store or log any credit card details unless they are fully PCI-DSS compliant.
This falls under your responsibility to ensure you do not produce code which circumvents our toolkits. We do not accept any liability for this.
3D Secure 2.0 (also known as EMV 3DS) is a new version of 3D Secure 1. 3D Secure 2.0 aiming to improve the security and consumer experience, including helping merchants achieve Strong Customer Authentication (SCA) compliance under PSD2.
The Payment Services Directive (PSD2), has introduced a new regulatory requirement: Strong Customer Authentication (SCA), with the aim to add an increased layer of security for card not present transactions, when making mobile and online payments. 
For more information, see Integrating 3D Secure 2 (EMV 3D Secure)﻿.
﻿
﻿
What is Strong Customer Authentication?
The Payment Services Directive (PSD2), has introduced a new regulatory requirement: Strong Customer Authentication (SCA). 
The aim of the SCA is to add an increased layer of security for card not present transactions, when making mobile and online payments.
To authenticate the transaction, merchants can verify the consumer's identity with the issuer. To be compliant with SCA, 3D Secure 2 transactions have additional authentication and transaction information within the payment flow.
This new version of 3D Secure, offers a better user experience and helps to minimise some of the friction the authentication adds to the checkout flow.
SCA requires authentication to use at least two of the following three aspects:
Something the consumer knows.
For example, password or PIN.
Something the consumer has. 
For example, phone or hardware token.
Something the consumer is.
For example, fingerprint or face recognition.
﻿
Exemptions to Strong Customer Authentication
Merchants can request specific Customer-Initiated-Transactions (CIT)s be exempt from strong customer authentication (EMV 3D Secure). 
This has the benefit of reducing friction for your customers and related checkout drop-outs.
Judopay will not currently automatically apply for transaction exemptions on behalf of the merchant.
﻿
Available Exemptions
Low-Value Transactions:
Transactions up to £45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of £100.
The consecutive transactions and cumulative limit are made up of all transactions against the card and not the merchant. 
When the limit is reached, the Issuer will request the consumer to be challenged, before authorising the transaction.
Low-Risk Transactions:
The Transaction Risk Analysis (TRA) exemption flag allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.
Trusted Beneficiaries (Whitelisting):
This exemption flag gives the card holder the option to add the merchant to their trusted list.
Secure Corporate Payments:
Request exemption for payments made using a corporate card.
﻿
Exemption Flags
Exemption flags provide you with the option to request the issuer, to not challenge the card holder at the time of the transaction.
Judopay has introduced the following exemption flags for you to add per transaction:
ChallengeRequestIndicator
Indicates the type of challenge request:
No Preference
No Challenge
Challenge Preferred
Challenge As Mandate
ScaExemption
The Customer-Initiated-Transaction (CIT) type, that is exempt from SCA.
This is subject to the Issuer’s decision; they do not have to honour this request and can reject authentication with a soft decline.

A soft decline is where the issuer rejects the exemption and requests the card holder be challenged for 3D Secure.
For more information, see Payment Flow﻿.
﻿
3D Secure 2 Best Practices
Here are some best practices for leveraging 3D Secure 2 to its full potential.
1
Adopt a frictionless flow, where possible. 
To maximise the chances of your customers experiencing a frictionless payment…
Leverage data points.
Ensure that you’re collecting and sending all of the recommended data points, such as device information, transaction history and customer behaviour. 
The more data the Issuer receives, the better, as it can help them to determine that the cardholder is legitimate and allow a frictionless flow. 
The following parameters are to be sent in every 3D Secure authentication request:
Browser IP address
Cardholder name
Cardholder email address or phone number
As 3D Secure continues to evolve, updates are often made to the types of data points that need to be sent with every transaction. 
Keeping up to date with these changes can lead to higher approval rates and a better customer experience. 
For more details on the mandatory data points and any updates check out our Docs here.
2
Benefit from Step-Up Authentication.
If an Issuer is unsure whether a transaction is legitimate, a transaction may be soft declined.
To tackle this and improve approval rates, one feature you can benefit from is step-up authentication. 
With step-up authentication, if a transaction is soft declined the customer can be prompted to provide additional information such as an OTP. This sends additional data to the Issuer to help prove that the cardholder is legitimate, allowing the transaction to proceed successfully. 
Tips for step-up authentication:
Offer multiple authentication methods
Provide customers with a variety of authentication options, such as SMS, OTP etc. This flexibility ensures that customers can complete the authentication in a way that is most convenient for them.
Optimise the step-up flow
Ensure that the step-up flow is as seamless as possible. This means optimising the UI for mobile devices, reducing load times, and providing clear instructions to the customer.
3
Don’t forget to optimise for mobile.
With the rise of mobile and app commerce, it is critical that your 3DS2 flow is optimised for mobile devices. This isn’t just about making sure that your payment page is responsive, it is ensuring that the entire authentication flow is smooth and user-friendly on smaller screens. 
Considerations for mobile optimisations include:
In-app authentication
Do you have a mobile app? Consider implementing in-app 3DS2 authentication. This approach keeps the customer within the app during the authentication process, reducing the risk of drop-off.
Test across multiple devices
Ensure that the 3DS2 flow works smoothly across a wide range of devices and operating systems.
4
Check if any of your transactions are exempt.
Exempt transactions = you can choose to tell the card Issuer that you want these types of transactions to be exempt.

Out of scope = these transactions won’t go through 3DS2 if  you send data with the transactions that shows that they are out of scope.
This list may evolve over time, but exemptions include:
Merchant-initiated transactions (MIT) / Recurring payments (out-of-scope)
Low-value payments (exempt)
Mail orders & Telephone orders (MOTO) (out-of-scope)
Low risk transactions (exempt)
Corporate payments, where a dedicated B2B payment method is used (exempt)
To enable or not enable? This really depends on your business. Just because you can make certain transactions exempt doesn’t always mean you should. 
5
Monitor and optimise performance. 
It is crucial to continuously monitor performance and make updates as and when needed. 
Tips for optimising your 3DS2 flow include:
Monitoring approval rates
Keeping an eye on your approval rates will be a key indicator if your flow is working well or needs adjusting. 
If you begin to notice a decrease in your approval rates, speak to your payment provider to explore possible causes and a solution.
A / B testing
It can be tricky to find that balance between security and user experience. A / B testing can help determine which authentication methods and flows give the best conversion rates while keeping your transactions secure.
6
Stay compliant with regulations. 
Regulations regarding online payments and customer authentication are regularly updated, and can vary region by region. 
To remain compliant:
Understand local requirements
Ensure that your 3DS2 implementation meets the specific requirements of the regions where your business is operating.
Update, as and when, regulations evolve
It is important to stay informed and update your flows accordingly. Work with a payment provider that will keep you up-to-date with regulatory changes and ensure that you stay compliant.
By following these best practices, you can ensure that your 3D Secure 2 implementation will be both effective and customer-friendly.
﻿
3D Secure 2 Device Data Collection
When authenticating a 3D Secure 2 (EMV 3D Secure) card payment, Judopay collects specific device data captured via Judokit and our Android and iOS SDKs. We share these details with both the card network and issuing bank.
This is an (EMV) 3DS2 protocol requirement, enabling the card network and issuing bank to recognise repeat transactions from the same device, mitigating transaction risk.
﻿
What Device Data is being Collected?
We have implemented the (EMV) 3DS2 protocol and collect the recommended 150 data elements detailed in the (EMV) 3-D Secure-SDK-Device Information Specification document. See the EMV Specifications & Associated Bulletins page to search for the latest specification document.
This information is used in risk analysis by the card schemes and card issuing banks.
Among the data elements collected by Judopay's Judokit are key browser details such as:
IP address
User agent
Browser language
System time zone
Screen dimensions
Colour depth
For in-app payments, our Android and iOS SDKs collect the following key details among others, recommended in the (EMV) 3-D Secure-SDK-Device Information Specification:
App-specific device ID:
﻿identifierForVendor on iOS
﻿ANDROID_ID on Android 8.0 or higher
Any apps installed on a previous version to Android 8.0, will observe a global ANDROID_ID instead of an app-specific value.
Device model
OS version
System language
System country
System time zone
Screen dimensions
The Android and iOS SDKs encrypt the device data using a key held by the card network. Judopay’s servers do not have access to this data.
As per the (EMV) 3DS2 protocol, the Android and iOS SDKs perform basic checks to detect rooted devices. Only the Boolean value representing whether the check succeeded or failed, is transmitted to the server.
The components of the Android SDK involved in 3DS2 transactions are obfuscated.
﻿
When is the 3D Secure 2 Device Data Collected?
When the consumer taps the PAY button, the payment flow is triggered. The device data is collected at the stage when you call CARD_PAYMENT.
For more information, see Payment Flow﻿.
Collecting device data is a requirement of the (EMV) 3DS2 protocol and is only triggered during the 3DS2 payment flow.
﻿
Liability Shift
What is Liability Shift?
The 3D Secure liability shift is a rule protecting you from fraudulent transactions.
For example, if your consumer denies they authorised or made a purchase, (due to a lost or stolen card) and the 3D Secure authentication was successful (following either the frictionless or challenge flow), the liability for the payment shifts from you to the issuing bank.
If the 3D Secure authentication:
was attempted but not successful
could not be performed
failed
the liability does not shift and remains with you.
﻿
When Liability Shift does not apply
Liability shift does not apply to transactions where authentication is not performed:
When exemptions﻿ to SCA are used
﻿MITs﻿﻿
Recurring MITs﻿﻿
MOTO
﻿
Liability Shift Rules
﻿
Electronic Commerce Indicator
The Electronic Commerce Indicator (ECI) is a value returned by Directory Servers (for example Visa, Mastercard, American Express, JCB), which represents the authentication outcome of 3D Secure 2 transactions.
A cryptogram is a unique value returned by Directory Servers when authentication is successful. The liability shifts to the issuing bank when 3D Secure authentication is successful, except for a few cases where it depends on the cryptogram being available from the card scheme's directory server.
Card schemes observe liability shift rules based on a combination of ECI values and the presence of the cryptogram in the response from the Directory Server.
Authentication Successful
The liability shifts to the issuing bank when authentication is successful (following the frictionless or challenge flow), except for a few cases where it depends on the cryptogram being available.
3D Secure Authentication Result
Electronic Commerce Indicator
Card Scheme
Liability Shift
Tip
Authentication Successful
05
Visa
Amex
JCB
YES
﻿
Authentication Successful
02
N2
Mastercard
YES
﻿
Authentication Successful
06
Mastercard
NO
ECI value of 06 from Mastercard indicates the transaction is out of scope for Secure Customer Authentication.
In this case, the merchant is not covered by liability shift.
Authentication Successful
06
Visa
Amex
JCB
YES
ECI value of 6 when received along with a cryptogram when authenticating Visa, Amex, JCB cards, indicates the authentication is successful.
Authentication Successful
01
Mastercard
YES
ECI value of 1 received while authenticating Mastercard cards, indicates the authentication is performed by a stand-in service, and is classed as successful.
In this case, the merchant is covered by liability shift.
Authentication Attempted but not Successful
3D Secure Authentication Result
Electronic Commerce Indicator
Card Scheme
Liability Shift
Tip
Authentication Attempted but not Successful
06
Visa
Amex
JCB
NO
ECI value of 6 when received without a cryptogram when authenticating Visa, Amex, JCB cards, indicates the authentication has not been successful.
In this case, the merchant is not covered by liability shift.
Authentication Attempted but not Successful
04
Mastercard
NO
﻿
Authentication Attempted but not Successful
01
Mastercard
NO
ECI value of 1 when received without a cryptogram when authenticating Mastercard cards, indicates the authentication has not been successful.
In this case, the merchant is not covered by liability shift.
Authentication could not be Performed
3D Secure Authentication Result
Electronic Commerce Indicator
Card Scheme
Liability Shift
Authentication could not be Performed
Any values not already listed
ANY
NO
Authentication Failed
3D Secure Authentication Result
Electronic Commerce Indicator
Card Scheme
Liability Shift
Authentication Failed
07
00
Visa
Amex
JCB
NO
Authentication Failed
NO
Mastercard
NO
﻿
Merchant Initiated Transactions
﻿
﻿
3D Secure 2 Flow
In the 3D Secure 2 payment flow, the Issuer will make a decision on whether they have enough authentication data to proceed with the transaction, or if they require the cardholder to further authenticate the transaction with additional Strong Customer Authentication (SCA) checks.
The following example takes you through the payment flow using paymentSession to authenticate the transaction.
﻿
1
Create a /paymentsession.
Use the reference returned from the response to populate the request header in Step 2.
2
Send the authorisation request with the /payments request header, populated with the reference received in the /paymentsession response.
This step:
Checks if the card is enrolled to support 3D Secure 2.
Gathers the Device and Card Details.
3
The response will determine whether:
The consumer is challenged for additional information.
The consumer is not challenged, the transaction continues and the consumer is re-directed to the outcome screen.
4
If the consumer is challenged in order to process the transaction, the 3D Secure 2 challenge screen is presented to the consumer to enter a code or password.
You will be notified via your webhook URL when the consumer has successfully completed the challenge screen.
Resume the transaction flow by calling the /resume3ds endpoint.
5
Authorisation complete.
The consumer is redirected to the outcome screen.
3D Secure 2 introduces frictionless authentication.
﻿
Overview of the Frictionless and Challenge Flow
The transaction to be approved without the need for the cardholder to enter additional authentication details.
The acquirer, issuer, and card scheme are able to exchange the necessary information in the background, using the device data.
Frictionless Flow
﻿
Challenge Flow
If additional SCA checks are required from the cardholder, the transaction will follow the challenge flow.
An iframe (or similar prompt) will be presented to the cardholder to input additional authentication (something the cardholder knows, has or is),
﻿
﻿
Integrating 3D Secure 2 (EMV 3D Secure)
We have made it a simple implementation for you to upgrade and integrate 3D Secure 2 within your payment flow. 
Use Judopay’s Web SDK for an even simpler integration for 3D Secure 2. Only a few steps are needed to set up your integration, the SDK does the rest. 
﻿
﻿
Payment Flow
﻿
﻿
Integration Steps
This guide will take you through the steps to perform 3D Secure 2 authentication and authorisation, when integrating directly with Judopay's REST API.
Prerequisite
﻿
For the back-end server integration, make use of our:
Server SDKs:
.NET Integration (version 3.0.0 or higher)
PHP Integration (version 5.5 or higher)
Or,

Call our API directly using JSON (version 6.0.0.0 or higher)
﻿
Step One: Create a Payment Request 
Payments, PreAuths and CheckCard are all supported.
Once you have the card details and device information from your client-side, your back-end server will need to make a payment request to Judopay's Transaction API.
The Cv2 is not stored by Judopay's Transaction API.
You will need to store the CV2 and the version for the duration of the transaction, then delete them as soon as the transaction has completed.
Storing the version will not be required in future updates.
For the full /payments endpoint schema details and descriptions, see our Transaction API Reference here.
Sample Request:
.NET
PHP
JSON
{
  "cardNumber": 4111111111111111,
  "cv2": 452,
  "expiryDate": "12/25",
  "cardAddress": {
    "address1": "CardHolder House",
    "address2": "1 CardHolder Street",
    "town": "CardHolder Town",
    "postCode": "AB1 2CD",
    "countryCode": 826
  },
  "judoId": "yourJudoId",
  "yourConsumerReference": "yourConsumerReference",
  "yourPaymentReference": "yourPaymentReference",
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99
  },
  "amount": 12.99,
  "currency": "GBP",
  "cardHolderName": "John Doe",
  "mobileNumber": 7999999999,
  "phoneCountryCode": 44,
  "emailAddress": "[email protected]",
  "shippingAddress": {
    "isBillingAddress": true
  },
  "threeDSecure": {
    "authenticationSource": "Browser",
    "methodNotificationUrl": "https://api.judopay.com/order/3ds/methodNotification",
    "challengeNotificationUrl": "https://api.judopay.com/order/3ds/challengeNotification",
    "challengeRequestIndicator": "challengeAsMandate"
  }
}
{
  "cardNumber": 4111111111111111,
  "cv2": 452,
  "expiryDate": "12/25",
  "cardAddress": {
    "address1": "CardHolder House",
    "address2": "1 CardHolder Street",
    "town": "CardHolder Town",
    "postCode": "AB1 2CD",
    "countryCode": 826
  },
  "judoId": "yourJudoId",
  "yourConsumerReference": "yourConsumerReference",
  "yourPaymentReference": "yourPaymentReference",
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99
  },
  "amount": 12.99,
  "currency": "GBP",
  "cardHolderName": "John Doe",
  "mobileNumber": 7999999999,
  "phoneCountryCode": 44,
  "emailAddress": "test.user@judopay.com",
  "shippingAddress": {
    "isBillingAddress": true
  },
  "threeDSecure": {
    "authenticationSource": "Browser",
    "methodNotificationUrl": "https://api.judopay.com/order/3ds/methodNotification",
    "challengeNotificationUrl": "https://api.judopay.com/order/3ds/challengeNotification",
    "challengeRequestIndicator": "challengeAsMandate"
  }
}
﻿
If no additional transaction checks are required, you will receive the usual  paymentReceipt response.
If additional transaction checks are required, you will receive the challenge response.
Notification URLs
You will need to set up two endpoints for your client to receive event notifications from the Issuer's ACS:
3DS Method Completion: Informs your client application that the ACS has completed device detail gathering.
methodNotifcationURL
ACS Challenge Completion: Informs your client application that the challenge has been completed by the customer.
challengeNotificationURL
Each endpoint should be configured to accept:
HTTP POST
Base64 encoded values
﻿
Step Two: (Conditional) - Device Detail Gathering
Some Issuer ACS’ support device data gathering.
Skip this step if no method URL is provided in the response from the API.
Check the response from Step One: Create a Payment Request﻿.
The following fields in the response will indicate if the device details have been requested by the issuer:
The result field: "Additional device data is needed for 3D Secure 2"
The message field: "Issuer ACS has requested additional device data gathering"
A methodURL will be returned in the response from the initial payment request.
In this instance, the following steps will need to be performed.
Render a hidden iFrame on the client-side targeting the methodURL
Rendering a Hidden iFrame
<!DOCTYPE html>
<html>

<head>
  <meta charset="ISO-8859-1">
  <title>Sample Open Method URL Page</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
  <script>
    $(document).ready(function() {
      console.log("ready!");
      var form = document.createElement("form");
      form.setAttribute("method", "POST");
      form.setAttribute("action", "https://test.portal.gpwebpay.com/pay-sim-gpi/sim/acs");
      form.setAttribute("target", "hidden_iframe");

      var threeDSMethodData = document.createElement("input");
      threeDSMethodData.setAttribute("type", "hidden");
      threeDSMethodData.setAttribute("name", "threeDSMethodData");
      
      // Set the md returned by the transaction api as the value:
      
      threeDSMethodData.setAttribute("value",
        "ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYjA2NmFhYWEtMjQxOS00YzcyLThhMWItYmNjZDg0ZDNiZTA5IiwKICAidGhyZWVEU01ldGhvZE5vdGlmaWNhdGlvblVSTCIgOiAiaHR0cDovL2xvY2FsaG9zdDo4MDAwL21ldGhvZC1ub3RpZmljYXRpb24iCn0");
      form.appendChild(threeDSMethodData);
      document.body.appendChild(form);

      form.submit();
      console.log("form submitted");
    });
  </script>
</head>

<body>
  <iframe id="hidden_iframe" name="hidden_iframe" style="display: none;"></iframe>
</body>

</html>
<!DOCTYPE html>
<html>

<head>
  <meta charset="ISO-8859-1">
  <title>Sample Open Method URL Page</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
  <script>
    $(document).ready(function() {
      console.log("ready!");
      var form = document.createElement("form");
      form.setAttribute("method", "POST");
      form.setAttribute("action", "https://test.portal.gpwebpay.com/pay-sim-gpi/sim/acs");
      form.setAttribute("target", "hidden_iframe");

      var threeDSMethodData = document.createElement("input");
      threeDSMethodData.setAttribute("type", "hidden");
      threeDSMethodData.setAttribute("name", "threeDSMethodData");
      
      // Set the md returned by the transaction api as the value:
      
      threeDSMethodData.setAttribute("value",
        "ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYjA2NmFhYWEtMjQxOS00YzcyLThhMWItYmNjZDg0ZDNiZTA5IiwKICAidGhyZWVEU01ldGhvZE5vdGlmaWNhdGlvblVSTCIgOiAiaHR0cDovL2xvY2FsaG9zdDo4MDAwL21ldGhvZC1ub3RpZmljYXRpb24iCn0");
      form.appendChild(threeDSMethodData);
      document.body.appendChild(form);

      form.submit();
      console.log("form submitted");
    });
  </script>
</head>

<body>
  <iframe id="hidden_iframe" name="hidden_iframe" style="display: none;"></iframe>
</body>

</html>
﻿
2. POST the 3DS Method Data (md) object to it.

The md is an encoded base 64 value containing the:
threeDSServerTransID 
and
NotificationURL 
as JSON.


(It is also returned in the Transaction API response from  Step One: Create a Payment Request ﻿).


3. Listen for the redirect of the methodNotificationUrl
We recommend you time-out after 10 seconds if you have not received a response from any NotificationURLs or rendered the methodURL from Step Two: (Conditional) - Device Detail Gathering .﻿﻿
﻿
Step Three: (Conditional) - Resume Transaction 
Once the device details have been gathered, the 3D Secure authentication flow needs to be resumed.
Render a hidden iFrame on the client-side targeting the methodNotificationURL
Listen for the redirect of the methodNotificationUrl where the method completion message is received.
Resume the 3D Secure flow by submitting the results of the device detail gathering.
For the full /resume3ds endpoint schema details and descriptions, see our Transaction API Reference here.
Sample Request:
.NET
PHP
JSON
// (1) Once the additional device data has been collected, create an instance of the ResumeThreeDSecureTwo Model:

var resumeModel = new ResumeThreeDSecureTwoModel()
{
    CV2 = "452",
    MethodCompletion = MethodCompletion.No
   };

// (2) Resume the transaction flow to Judopay: 
//Use the ReceiptId from the original response

var resumeResult = await client.ThreeDs.Resume3DSecureTwo(result.Response.ReceiptId, resumeModel);

// (1) Once the additional device data has been collected, create an instance of the ResumeThreeDSecureTwo Model:

var resumeModel = new ResumeThreeDSecureTwoModel()
{
    CV2 = "452",
    MethodCompletion = MethodCompletion.No
   };

// (2) Resume the transaction flow to Judopay: 
//Use the ReceiptId from the original response

var resumeResult = await client.ThreeDs.Resume3DSecureTwo(result.Response.ReceiptId, resumeModel);
﻿
methodCompletion value:
methodCompletion = Yes
If your client received a POST to the methodNotifcationURL
methodCompletion = No
If your client did NOT receive a POST to the methodNotifcationURL
methodCompletion = Unavailable
If your client was unable to render the methodURL
﻿
primaryAccountDetails Block:
The primaryAccountDetails block is optional, however it is mandatory for merchants who have an MCC code of 6012 to submit additional Information about the primary account holder for payment pre-authorisation.
Example primaryAccountDetails Block
"primaryAccountDetails": {  
    "name": "Smith", 
    "accountNumber": "1234567890", 
    "dateOfBirth": "1980-01-01", 
    "postCode": "AB1 2CD"
}
"primaryAccountDetails": {  
    "name": "Smith", 
    "accountNumber": "1234567890", 
    "dateOfBirth": "1980-01-01", 
    "postCode": "AB1 2CD"
}
﻿
﻿
Step Four: (Conditional) - Render Challenge Page
After you have resumed the transaction, check the response from Step Three: (Conditional) - Resume Transaction﻿.
Sample Response
{
    "challengeUrl": "https://mysampleapp/challenge/",
    "cReq": "ewo8fdhJKESWujmlpsalIiA6ICIwMSIKfQ",
    "version": "2.1.0",
    "receiptId": "123456789",
    "result": "Challenge completion is needed for 3D Secure 2",
    "message": "Issuer ACS has responded with a Challenge URL",
    "md": "zNkcy9tZXRob2ROb3RpZmljYXRp9ojhFSik9"
}
{
    "challengeUrl": "https://mysampleapp/challenge/",
    "cReq": "ewo8fdhJKESWujmlpsalIiA6ICIwMSIKfQ",
    "version": "2.1.0",
    "receiptId": "123456789",
    "result": "Challenge completion is needed for 3D Secure 2",
    "message": "Issuer ACS has responded with a Challenge URL",
    "md": "zNkcy9tZXRob2ROb3RpZmljYXRp9ojhFSik9"
}
﻿
The following fields in the response will indicate if your customer's bank may want to challenge:
The result field: "Challenge completion is needed for 3D Secure 2"
The message field: "Issuer ACS has responded with a Challenge URL"
A challengeURL: to render the challenge page iFrame for your customer 
Render the challengeURL for your customer to complete the challenge.
Rendering challengeUrl Page Example
<!DOCTYPE html>
<html>

<head>
  <meta charset="ISO-8859-1">
  <title>Sample Open Challenge URL Page</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
  <script>
    $(document).ready(function() {
      console.log("ready to render challenge")
      var form = document.createElement("form");
      form.setAttribute("method", "POST");
      form.setAttribute("action", "https://test.portal.gpwebpay.com/pay-sim-gpi/sim/acs");
      form.setAttribute("target", "iframe");

      var creqData = document.createElement("input");
      creqData.setAttribute("type", "hidden");
      creqData.setAttribute("name", "creq");
      //add creq object obtained from the server
      creqData.setAttribute("value", "ewogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcSIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5NGVjODA4NS02NmIyLTQ2MzQtOTg4Zi04YmYzYjBjMTgxNTMiLAogICJhY3NUcmFuc0lEIiA6ICJiNmI1YTYzOC0wYmE2LTRhYzQtYjA3Ni0zMGVlMmM2MmY1ZWMiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIiA6ICIwMSIKfQ==");
      form.appendChild(creqData);

      /* optional parameter to include Session Data

      */
      var sessionData = document.createElement("input");
      sessionData.setAttribute("type", "hidden");
      sessionData.setAttribute("name", "threeDSSessionData");
      sessionData.setAttribute("value", "<some judo specific data here");
      form.appendChild(sessionData);

      document.body.appendChild(form);
      console.log("submitting form")
      form.submit();
      console.log("complete")
    });
  </script>
</head>
<body>
</body>
</html>
<!DOCTYPE html>
<html>

<head>
  <meta charset="ISO-8859-1">
  <title>Sample Open Challenge URL Page</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
  <script>
    $(document).ready(function() {
      console.log("ready to render challenge")
      var form = document.createElement("form");
      form.setAttribute("method", "POST");
      form.setAttribute("action", "https://test.portal.gpwebpay.com/pay-sim-gpi/sim/acs");
      form.setAttribute("target", "iframe");

      var creqData = document.createElement("input");
      creqData.setAttribute("type", "hidden");
      creqData.setAttribute("name", "creq");
      //add creq object obtained from the server
      creqData.setAttribute("value", "ewogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcSIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5NGVjODA4NS02NmIyLTQ2MzQtOTg4Zi04YmYzYjBjMTgxNTMiLAogICJhY3NUcmFuc0lEIiA6ICJiNmI1YTYzOC0wYmE2LTRhYzQtYjA3Ni0zMGVlMmM2MmY1ZWMiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIiA6ICIwMSIKfQ==");
      form.appendChild(creqData);

      /* optional parameter to include Session Data

      */
      var sessionData = document.createElement("input");
      sessionData.setAttribute("type", "hidden");
      sessionData.setAttribute("name", "threeDSSessionData");
      sessionData.setAttribute("value", "<some judo specific data here");
      form.appendChild(sessionData);

      document.body.appendChild(form);
      console.log("submitting form")
      form.submit();
      console.log("complete")
    });
  </script>
</head>
<body>
</body>
</html>
﻿
Creq: Should be set to the cReq received in the response
threeDSSessionData: Can be set to contain any details you would like returned in the post.
Listen for the redirect of the challengeNotificationUrl
﻿
Step Five: Complete 3DS
Upon receiving a POST back to the challengeNotificationUrl send a request to Judopay's Transaction API to complete the transaction.
If no additional transaction checks are required, you will receive the usual paymentReceipt response.
If additional transaction checks are required, you will receive the completion response.
For the full /complete3dsendpoint schema details and descriptions, see our Transaction API Reference here.
Sample Request:
.NET
PHP
JSON
{
   "Cv2": "452",
   "Version": "2.0"
}
{
   "Cv2": "452",
   "Version": "2.0"
}
﻿
Judopay's Transaction API will respond with the both the:
Authentication
Authorisation status
of the transaction.
﻿
Upgrading your Integration to 3D Secure 2
﻿
Integrating via Web Payments
If you are currently using Web Payments Version 1, simply amend the URL in the redirect from ‘v1’ to 'v2’.
For example:
Version 1
Amended
JSON
"postUrl": "https://pay.judopay-sandbox.com/v1", 
"reference": "yth67_82nhjmf903jnmaiine…"
"postUrl": "https://pay.judopay-sandbox.com/v1", 
"reference": "yth67_82nhjmf903jnmaiine…"
﻿
JSON
"postUrl": "https://pay.judopay-sandbox.com/v2",       
"reference": "yth67_82nhjmf903jnmaiine…"
"postUrl": "https://pay.judopay-sandbox.com/v2",       
"reference": "yth67_82nhjmf903jnmaiine…"
﻿
For more details, see Web Payments Set Up﻿. 
﻿
Integrating via Web SDK
If you are currently using Web SDK Integration, we would recommend updating your integration to authenticate using Payment Session.
Simply:
Upgrade to the latest version (version 0.0.25 or higher) 
For more details, see Creating a 3D Secure 2 Payment with the Web SDK﻿.
﻿
Integrating via Mobile SDK
If you are currently using Mobile SDK integration, we would recommend updating your integration to the latest version of the SDK.
Version 3.0.0 or higher supports 3DS 2, helping your mobile app be SCA compliant. For more information see, What is Strong Customer Authentication?
For Android, see 3D Secure 2 for Android﻿.
For iOS, see  3D Secure 2 for iOS﻿.
For React Native, see 3D Secure 2 for React Native﻿.
﻿
Testing your Integration
To trigger specific 3D Secure 2 user journeys:
Include the cardHolderName as specified in the CardHolderName Table﻿﻿
The cardHolderName corresponds to an expected transaction result.
To test 3D Secure 2 user journeys, see Testing 3D Secure 2 Authentication﻿﻿
3D Secure Authentication Result	Electronic Commerce Indicator	Card Scheme	Liability Shift	Tip
Authentication Successful	05	Visa Amex JCB	YES
Authentication Successful	02 N2	Mastercard	YES
Authentication Successful	06	Mastercard	NO	ECI value of 06 from Mastercard indicates the transaction is out of scope for Secure Customer Authentication. In this case, the merchant is not covered by liability shift.
Authentication Successful	06	Visa Amex JCB	YES	ECI value of 6 when received along with a cryptogram when authenticating Visa, Amex, JCB cards, indicates the authentication is successful.
Authentication Successful	01	Mastercard	YES	ECI value of 1 received while authenticating Mastercard cards, indicates the authentication is performed by a stand-in service, and is classed as successful. In this case, the merchant is covered by liability shift.
3D Secure Authentication Result	Electronic Commerce Indicator	Card Scheme	Liability Shift	Tip
Authentication Attempted but not Successful	06	Visa Amex JCB	NO	ECI value of 6 when received without a cryptogram when authenticating Visa, Amex, JCB cards, indicates the authentication has not been successful. In this case, the merchant is not covered by liability shift.
Authentication Attempted but not Successful	04	Mastercard	NO
Authentication Attempted but not Successful	01	Mastercard	NO	ECI value of 1 when received without a cryptogram when authenticating Mastercard cards, indicates the authentication has not been successful. In this case, the merchant is not covered by liability shift.
3D Secure Authentication Result	Electronic Commerce Indicator	Card Scheme	Liability Shift
Authentication could not be Performed	Any values not already listed	ANY	NO
3D Secure Authentication Result	Electronic Commerce Indicator	Card Scheme	Liability Shift
Authentication Failed	07 00	Visa Amex JCB	NO
Authentication Failed	NO	Mastercard	NO
Updated 14 Oct 2024
Introducing 3D Secure 2
Fraud Prevention Solutions