Integration Steps

Integrating via our Transaction API

This guide will take you through steps one to five, to illustrate the full 3D Secure 2 authentication and authorisation flow (including the conditional steps), to verify how it relates to the user journey when integrating directly with Judopay's Transaction API.

When integrating via our Web and Mobile SDKs, we handle the 3D Secure flow, including the conditional steps on your behalf. Step One: Creating a Payment Session Request is the only step to be handled with ALL integration types.

Prerequisite

Make sure your account has 3D Secure 2 API credentials enabled. Contact Customer Support to set this up.

For the back-end server integration, make use of our:

Server SDKs:

.NET Integration (version 3.0.0 or higher)

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 for the duration of the transaction, then delete it as soon as the transaction has completed.

For the full /payments endpoint schema details and descriptions, see our Transaction API Reference here.

Sample Request:

// (1) Create an instance of the CardPaymentModel:
var paymentModel = new CardPaymentModel()
{  
     JudoId = "yourJudoId",
       YourConsumerReference = "yourConsumerReference",
       YourPaymentReference = "yourPaymentReference",
       Amount = 12.99,
       CardNumber = "1236358700088456",
       CV2 = "452",
       ExpiryDate = "12/30",
       CardAddress = new CardAddressModel
        {
         PostCode = "postCode"
        }
    CardHolderName = "CHALLENGE",
    MobileNumber = "07999999999",
    PhoneCountryCode = "44",
    EmailAddress = "[email protected]",
    ThreeDSecure = new ThreeDSecureTwoModel
    {
        AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser,
        ChallengeRequestIndicator = ThreeDSecureTwoChallengeRequestIndicator.ChallengeAsMandate,
        ScaExemption = ThreeDSecureTwoScaExemption.TransactionRiskAnalysis
    }
};

// (2) Send the 3ds2 request to Judopay
var result = await client.Payments.Create(paymentModel);


// (3) Challenge response example requesting additional device data is needed for 3D Secure 2
{
  "Response": {
    "ThreeDSecure": {
      "methodUrl": "https://example.com/pay-sim/sim/acs",
      "version": "2.1.0",
      "md": "ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYjNjY2IxYWItZTk5"
    },
    "receiptId": "68869013641206075392",
    "message": "Issuer ACS has requested additional device data gathering",
    "result": "Additional device data is needed for 3D Secure 2"
  },

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

<!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:

// (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, 6051 and 7299 to submit additional Information about the primary account holder for payment pre-authorisation.

"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.

{
    "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.

<!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:

// (1) Create an instance of the CompleteThreeDSecureTwo Model:
var completeModel = new CompleteThreeDSecureTwoModel()
{
    CV2 = "452",
    "primaryAccountDetails":{
      "name":"John Smith",
      "accountNumber":"123456",
      "dateOfBirth":"1980-01-01",
      "postCode":"EC2A 4DP"
   }
};

// (2) Complete the transaction flow to Judopay: 
var completeResult = await client.ThreeDs.Complete3DSecureTwo(result.Response.ReceiptId, completeModel);

Judopay's Transaction API will respond with the both the:

Authentication

Authorisation status

of the transaction.