To create a one-use token:

A sample success response:

{    
"oneUseToken": "2uhOsi...8KZcn=",    
 "cardLastfour": "3436",    
   "endDate": "12/20",    
    "cardScheme": "Visa",    
      "cardFunding": "Debit",    
        "error": false,     
   "clientDetails": 0 }

A sample error response:

{
    "error": 
    {
        "message": "Sorry, we're unable to process your request. Please check your details and try again."
    }
}

var encryptedCard = new RegisterEncryptedCardModel
{
    OneUseToken = oneUseToken,
    JudoId = judoId,
    YourConsumerReference = yourConsumerReference,
};

var response = client.RegisterCards.Create(encryptedCard);
var receipt = response.Response as PaymentReceiptModel;

if(receipt.Result === "Success") {
    var cardToken = receipt.CardDetails.CardToken;  
}

All fields required to run the 3D Secure check will be available in the receipt:

{
    "receiptId": "415874660497166336",
    "result": "Requires 3D Secure",
    "message": "Issuer authentication required",
    "acsUrl": "https://gw1.paymentsensegateway.com:4430/ACS/Default.aspx",
    "md": "1902...2484",
    "paReq": "eJxd...kqXcvg=="
}

To complete the transaction the 3D Secure form needs to be displayed to the consumer.

This can be achieved in any of the following ways: 

For more details, see 3D Secure.

The configuration file is key for customising the behaviour and look of the Iframe.

You can change the appearance, behaviour and language by passing a configuration JSON object into createCardDetails.

var styleOptions = {
    iframe {
        ...
    }
}
var judo = new JudoPay('Your Token', true);
var paymentFrame = judo.createCardDetails('', styleOptions)

The Web SDK has a default setting for all properties, you override these in the config file. 

The config file is a simple JSON object containing the following properties:

The configuration file is optional.

styles: {
            default: {
                field: {
                    backgroundColor: '#0a0a0a',
                    color: '#EEE',
                    padding: '10px',
                    margin: '0 20px',
                    width: '90%',
                    borderRadius: '4px',
                    boxShadow: 'rgba(255, 255, 255, 0.8) 0px 0px 10px inset'
                },
                label: {
                    color: '#EEE',
                    padding: '10px 10px 0 25px',
                    fontWeight: 'bold',
                    textTransform: 'capitalize'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#2a2a2a',
                    color: '#EEE'
                },
            },
            error: {
                field: {
                    backgroundColor: '#1a0a0a',
                    color: '#990000'
                }
            },
            valid: {
                field: {
                    color: '#CFC'
                }
            },
            cv2: {
                field: {
                    margin: "0 20px 10px;"
                },
                container: {
                    width: '47%',
                    paddingBottom: "20px"
                }
            },
            expiryDate: {
                field: {
                    marginBottom: "10px;"
                },
                container: {
                    width: '47%',
                    paddingBottom: "20px"
                }
            }

Three layout options are provided:

An array of JSON objects each representing a font, are added to the page.

They can be referenced from the Style object.

Each object can have the following properties:

The following example loads Roboto from Google fonts and assigns it:

fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange: 'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                },
                label: {
                    fontFamily: "'Roboto', sans-serif",
                }
            },

You can add any language you need.

To add a new language:

For the purpose of this exercise, the example shows how to add Romanian:

var customStyle = {
    iframe1 : {
        language : "ro",
        customLanguages : 
            {
                "ro" : {
                    fieldLabels: {
                        cardNumberLabel: "Număr de card",
                        expiryDateLabel: "Data Expirarii",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "Număr de card",
                        expiryDatePlaceholder: "LL / AA ",
                        cardVerificationCodePlaceholder: "CVC"
                    },
                    errors : {
                        0: "Numărul cardului poate conține numai numere",
                        1: "Numărul cardului nu este valid",
                        2: "Tipul de card nu este recunoscut, verificați din nou numărul dvs",
                        3: "Numarul cardului este necesar",
                        4: "Cardul a expirat",
                        5: "Data expirării cardului nu este validă",
                        6: "Data expirării necesară",
                        7: "Codul {0} este prea scurt pentru cartea de {1}",
                        8: "Codul {0} este prea lung pentru carte de {1}",
                        9: "Codul {0} poate conține numai numere",
                        10: "Codul {0} necesar pentru cartea de {1}"
                    }
                }
            },
           ...
    }
};

Now all strings used in the application will be taken from the new language set.

As well as adding any language into the customLanguages property, also set the language for the error code (ro). 

It is recommended to copy this example and change the strings when defining your new language.

Judopay's Web SDK supports multiple languages.

var customStyle = {
    iframe1 : {
        language : "es"
        ...
    }
}

You can change the language used in the form at run time. This is useful for consumers running a Single Page Application (SPA).

The JudoPay object which initialises the form provides a method for updating a language. You can hook this method up to a button/event of your choice for dynamically changing the language. 

In the example below, a method is added to an anchor element on the checkout page, which will change the language used after the iframe is already initialised.

<script>
    var judo = new JudoPay('Your Token', true);
</script>
<a href="javascript:judo.changeIframeLanguage('de');">de</a>

Configuration Example

Below is an example config file which sets the styles for:

It also modifies the error and UI strings for the default language: English.

var exampleConfig = {
    iframe: {
        language: 'en',
        errorFieldId: 'judopay-errors-2',
        showCardTypeIcons: true,
        cardTypeIconRight: '10px',
        cardTypeIconTop: '-2px',
        backgroundColor: '#e5e5e5',
        layout: "compact",
        fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange:
                'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                    fontSize: '17px',
                    backgroundColor: '#e5e5e5',
                    borderTop: 'none',
                    borderRight: 'none',
                    borderLeft: 'none',
                    boxShadow: 'none',
                    margin: '-10px 0 -5px',
                    padding: '6px 0'
                },
                label: {
                    color: '#F77',
                    fontFamily: "'Roboto', sans-serif",
                    opacity: '0',
                    height: '15px',
                    fontSize: '8px',
                    display: 'inline-block',
                    transition: 'opacity 0.6s',
                    marginLeft: '5px',
                    position: 'relative',
                    bottom: '-10px',
                    zIndex: '100'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#F0F0F0',
                    color: 'rgb(130, 130, 130)',
                    padding: '12px 6px 0',
                    fontSize: '16px',
                },
                label: {
                    opacity: "1",
                    color: 'rgb(130, 130, 130)'
                }
            },
            error: {
                field: {
                    backgroundColor: '#e5ecff',
                    padding: '12px 6px 0',
                },
                label: {
                    opacity: "1"
                }
            },
            valid: {
                field: {
                    backgroundColor: '#e5ffec',
                    color: 'green',
                    padding: '12px 6px 0',
                },
                label: {
                    color: 'green',
                    opacity: "1"
                }
            },
            customLanguages: {
                "en": {
                    fieldLabels: {
                        cardNumberLabel: "Credit Card Number",
                        expiryDateLabel: "Expiration Date",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "xxxx xxxx xxxx xxxx",
                        expiryDatePlaceholder: "MM / YY ",
                        cardVerificationCodePlaceholder: "xxx"
                    },
                    errors: {
                        0: "Card number must be numeric",
                        1: "Card number not valid",
                        2: "Card type not recognised",
                        3: "Card number required",
                        4: "Card is expired",
                        5: "Invalid expiry date",
                        6: "Expiry date required",
                        7: "{0} code too short",
                        8: "{0} code too long",
                        9: "{0} code must be numeric",
                        10: "{0} code required"
                    }
                }
            }
        }
    }
}

You can also modify the language to change the phrasing, words and dialects used

For the purpose of this exercise, the Romanian language is added in this example, to illustrate how multiple dictionaries can be added if customLanguages is defined as an array:

var customStyle = {
    iframe1 : {
        language : "en",
        customLanguages : [
        {
                "en" : {
                    fieldLabels: {
                        cardNumberLabel: "Credit Card Number",
                        expiryDateLabel: "Expiration Date",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "xxxx xxxx xxxx xxxx",
                        expiryDatePlaceholder: "MM / YY ",
                        cardVerificationCodePlaceholder: "xxx"
                    },
                    errors : {
                        0: "Card number must be numeric",
                        1: "Card number not valid",
                        2: "Card type not recognised",
                        3: "Card number required",
                        4: "Card is expired",
                        5: "Invalid expiry date",
                        6: "Expiry date required",
                        7: "{0} code too short",
                        8: "{0} code too long",
                        9: "{0} code must be numeric",
                        10: "{0} code required"
                    }
                }
            },
            {
                "ro" : {
                    fieldLabels: {
                        cardNumberLabel: "Număr de card",
                        expiryDateLabel: "Data Expirarii",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "Număr de card",
                        expiryDatePlaceholder: "LL / AA ",
                        cardVerificationCodePlaceholder: "CVC"
                    },
                    errors : {
                        0: "Numărul cardului poate conține numai numere",
                        1: "Numărul cardului nu este valid",
                        2: "Tipul de card nu este recunoscut, verificați din nou numărul dvs",
                        3: "Numarul cardului este necesar",
                        4: "Cardul a expirat",
                        5: "Data expirării cardului nu este validă",
                        6: "Data expirării necesară",
                        7: "Codul {0} este prea scurt pentru cartea de {1}",
                        8: "Codul {0} este prea lung pentru carte de {1}",
                        9: "Codul {0} poate conține numai numere",
                        10: "Codul {0} necesar pentru cartea de {1}"
                    }
                }
            }
    ],
        ...        
    }
};

Below is an example config file which sets the layout, background colour, input and label styles.

It also modifies the error and UI strings for the default language: English.

var exampleConfig = {
    iframe: {
        language: 'en',
        errorFieldId: 'judopay-errors-2',
        showCardTypeIcons: true,
        cardTypeIconRight: '10px',
        cardTypeIconTop: '-2px',
        backgroundColor: '#e5e5e5',
        layout: "compact",
        fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange:
                'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                    fontSize: '17px',
                    backgroundColor: '#e5e5e5',
                    borderTop: 'none',
                    borderRight: 'none',
                    borderLeft: 'none',
                    boxShadow: 'none',
                    margin: '-10px 0 -5px',
                    padding: '6px 0'
                },
                label: {
                    color: '#F77',
                    fontFamily: "'Roboto', sans-serif",
                    opacity: '0',
                    height: '15px',
                    fontSize: '8px',
                    display: 'inline-block',
                    transition: 'opacity 0.6s',
                    marginLeft: '5px',
                    position: 'relative',
                    bottom: '-10px',
                    zIndex: '100'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#F0F0F0',
                    color: 'rgb(130, 130, 130)',
                    padding: '12px 6px 0',
                    fontSize: '16px',
                },
                label: {
                    opacity: "1",
                    color: 'rgb(130, 130, 130)'
                }
            },
            error: {
                field: {
                    backgroundColor: '#e5ecff',
                    padding: '12px 6px 0',
                },
                label: {
                    opacity: "1"
                }
            },
            valid: {
                field: {
                    backgroundColor: '#e5ffec',
                    color: 'green',
                    padding: '12px 6px 0',
                },
                label: {
                    color: 'green',
                    opacity: "1"
                }
            },
            customLanguages: {
                "en": {
                    fieldLabels: {
                        cardNumberLabel: "Credit Card Number",
                        expiryDateLabel: "Expiration Date",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "xxxx xxxx xxxx xxxx",
                        expiryDatePlaceholder: "MM / YY ",
                        cardVerificationCodePlaceholder: "xxx"
                    },
                    errors: {
                        0: "Card number must be numeric",
                        1: "Card number not valid",
                        2: "Card type not recognised",
                        3: "Card number required",
                        4: "Card is expired",
                        5: "Invalid expiry date",
                        6: "Expiry date required",
                        7: "{0} code too short",
                        8: "{0} code too long",
                        9: "{0} code must be numeric",
                        10: "{0} code required"
                    }
                }
            }
        }
    }
}

The Web SDK is designed to provide feedback quickly and clearly to the consumer.

To display error messages:

Add a div with the id judopay-errors on your page, ideally below the iframe:

<div class="judopay-errors"></div>;

The table below displays all errors that can be returned:

For errors 7-10; the numbers appear in curly brackets. These will be changed into values depending on the current state of the iframe form.

For example:

{0} will change to the card verification code acronym. This is named differently depending on the card type (e.g. CVC, CVV).

{1} will refer to the detected card type, for example Visa, Mastercard or Discover.

If the iframe has detected a Visa number, the following error message transform would occur:

{0} code too long for {1} card" -> "CVC code to long for Visa card

A similar error with an American Express card, the message would appear as:

"CID code too long for American Express card"

Judopay's Web SDK requires some additional processing steps, in order to achieve a successful 3D Secure version 1.0 transaction.

This guide assumes the following prerequisites:   

To customise and create the Judopay WebSDK iframe:

<script>var configMinimum = {
iframe: {
language: "en",
    	errorFieldId: 'judopay-errors',
    	showCardTypeIcons: true,
    	cardTypeIconRight: "10px",
    	cardTypeIconTop: "-2px",
    	backgroundColor: "#FFFFFF",
    	layout: "compact",
    	enabledPaymentMethods: ['CARD'],
    	isCountryAndPostcodeVisible: false,
    	errorsDisplay: "HIDE_UNDER_FIELDS",
    	disableUnderline: false,
    }
}
</script>

For the purpose of this exercise, this sample config sets the following options for the iframe:

var judo = new JudoPay("yourAPIToken", true);
var payment = judo.createCardDetails('payment-iframe',configMinimum);

Complete customisation of the iframe settings and styles can be found here.

Once you have an established Judopay WebSDK iframe and after the consumer has entered valid card details (the iframe handles the validation and errors of this entry), on clicking the Pay Now button (submit-payment-button) you will obtain a promise from Judopay's servers which will return a oneUseToken for use within 30 minutes to transact the payment.

The following script:

To setup a payment promise on the Pay Now button:

var paymentPromise = "";
$("#submit-payment-button").click(function(){
   if (judo.getPaymentMethod()=="CARD") {
  	var paymentPromise = judo.createToken(payment);
  	paymentPromise.then(function(result) {
     	if (typeof result.error !== 'undefined') {
        	if (typeof result.oneUseToken !== 'undefined') {
 
            	  	// This is where the token is sent to your back office for payment
         	// request (expanded example below)
 
        	}
     	} 
  	}
   }
}

This example expands on Step 2: Obtain the Payment Promise above, with the source code to handle the oneUseToken and then submit this to the merchant’s server.

$.get("handle3.php",{myToken : result.oneUseToken}, function(data) {

// Code in here to handle the result from the oneUseToken Request will be inserted
// Here and handled in Step 5: Handle the Response from Judopay's Servers
}
);

This example should be called handle3.php and is the receiving handler from the Step 3: A oneUseToken is sent to Merchant's Server section above.

This example:

<?php
header('Access-Control-Allow-Origin: *');
header('Content-Type: application/json');
 
$OneUseToken = $_GET["myToken"];
 
$userEncode = base64_encode("yourAPIToken:yourAPISecret");
$data=json_encode(
array(
'oneUseToken' =>$OneUseToken,
'yourConsumerReference' =>substr(md5(rand()), 0, 7),
'yourPaymentReference' => substr(md5(rand()), 0, 7), 	
'judoId' => 'yourJudoId',
'amount' => 1.0,
'currency' => "GBP"
));
$headers = array(
Content-Type:application/json',
'Authorization: Basic '.$userEncode,
'API-Version: 5.7.1',
);
$ch = curl_init("https://gw1.judopay-sandbox.com/transactions/payments");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
 
echo $response;
 
?>

Extend the handler in Step 3: A oneUseToken is sent to Merchant's Server to handle the response.

$.get("handle3.php",{myToken : result.oneUseToken}, function(data) {

   if (data.result=="Requires 3D Secure") {
      // Create a Hidden form to Submit to the 3DS Issuer
      const form = document.createElement('form');
      form.method = 'post';
      form.action = data.acsUrl;
      const hiddenField = document.createElement('input');
      document.createElement('input');
      hiddenField.type = 'hidden';
      hiddenField.name = 'MD';
      hiddenField.value = data.md;
      form.appendChild(hiddenField);
      const hiddenField2 = document.createElement('input');
      document.createElement('input');
      hiddenField2.type = 'hidden';
      hiddenField2.name = 'PaReq';
      hiddenField2.value = data.paReq;
      form.appendChild(hiddenField2);
      const hiddenField3 = document.createElement('input');
      document.createElement('input');
      hiddenField3.type = 'hidden';
      hiddenField3.name = 'TermUrl';
      hiddenField3.value = 'https://www.yourdomain.com/return3ds.php?receiptId='+data.receiptId;
      form.appendChild(hiddenField3);
      document.body.appendChild(form);

      // Submit the form to redirect the user to the 3DS Issuer
      form.submit();
   }
}
);

This is a return location on your server (the result of the 3D Secure Challenge will be POSTed to this location). You should change this to your own public facing domain.

The source code from Step 5: Handle the Response from Judopay's Servers, will automatically submit the 3D Secure parameters to the required Issuer Service.

The consumer will be re-directed to the Issuer Service 3D Secure Challenge Screen:

If the consumer completes the 3D Secure challenge screen:

If the consumer chooses to abandon at this stage, you will receive a no reply POST.

This example is the return3ds.php file as declared in the sample code from Step 5: Handle the Response from Judopay's Servers.

The following sample POSTs the returned 3D Secure response back to Judopay via an API call to the /transactions endpoint, with the given receiptId.

<?php

$receiptId = $_GET['receiptId'];1

if (empty($receiptId))  {
  echo '<BR> Sorry there was an error - missing receiptId';2
} else {
  $MD = $_POST['MD'];
  $PaRes = $_POST['PaRes'];
  $data = json_encode(array('Md' =>$MD,'PaRes' =>$PaRes));3
  $userEncode = base64_encode("yourAPIToken:yourAPISecret");4
  $headers = array(
  'Content-Type:application/json',
  'Authorization: Basic '.$userEncode,
  'API-Version: 5.7.1',
  );
  $ch = curl_init("https://gw1.judopay-sandbox.com/transactions/".$receiptId);5
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);6
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
  curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  echo $response;7
}
?>

{"receiptId":"615495218204119040",
"yourPaymentReference":"bbd5067",
"type":"Payment",
"createdAt":"2020-08-25T11:38:06.7811+01:00",
"result":"Success",
"message":"AuthCode: 058967",
"judoId":100183086,
"merchantName":"testmerchant",
"appearsOnStatementAs":"APL*/testmerchant ",
"originalAmount":"1.00",
"netAmount":"1.00",
"amount":"1.00",
"currency":"GBP",
"cardDetails":
{"cardLastfour":"6891",
   "endDate":"1220",
   "cardToken":"DgoimaGqpm8ngRKnAl7xgXvFS0zuf3JQ",
   "cardType":1,
   "cardScheme":"Visa",
   "cardFunding":"Credit",
   "cardCategory":"",
   "cardQualifier":0,
   "cardCountry":"FR",
   "bank":"Credit Industriel Et Commercial"},
"consumer":
{"consumerToken":"dQxfNBY5cddXeMhe",
   "yourConsumerReference":"3190912"
},
"riskScore":0,
"threeDSecure":
{"attempted":true,
   "result":"PASSED"},
"externalBankResponseCode":"",
"billingAddress":{}
}

As a result of the receiptObject received in Step 5: Handle the Response from Judopay's Servers, you should redirect the consumer accordingly.

For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.

You could store the:

Using those tokens bypasses the need to enter any card details if required.