Authentication
Integration Steps

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.
Updated 31 Jan 2025
Did this page help you?
3D Secure 2 Payment Flow
Exemptions to SCA