Web SDK

Web SDK
Judopay's Web SDK is a JavaScript library which includes a fully customisable hosted iframe solution enabling you to collect sensitive card information.
You will not take on additional PCI scope, as sensitive card information such as:
card number (PAN)
expiry date
CV2 
will be submitted by your customers into fields hosted by Judopay.
﻿
Web SDK Video Tutorials
﻿
﻿
Payment Flow
﻿
﻿
Creating a 3D Secure 2 Payment with the Web SDK
When authorising /payments or /preauths it is recommended to use paymentSession.
Web SDK Version 0.0.29 (and higher) fully supports 3D Secure 2 flows. No additional support is required, the SDK does the rest.
﻿
﻿
The following steps are prerequisites for all the payment methods﻿ available for integration using Judopay's Web SDK.
Step One: Create a paymentSession
﻿
﻿
Make a HTTP POST Request: /paymentsession
Payment Session Request Example
Response Reference Example
{
  "judoId": "100100100",
  "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
  "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134",
  "currency": "GBP",
  "amount": 10.99,
  "expiryDate": "2024-02-05T16:28:32.8596+00:00" //if not set, session will expire in 30 minutes
}
{
  "judoId": "100100100",
  "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
  "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134",
  "currency": "GBP",
  "amount": 10.99,
  "expiryDate": "2024-02-05T16:28:32.8596+00:00" //if not set, session will expire in 30 minutes
}
﻿
﻿
Your backend server should store the paymentSession response reference returned by Judopay's API.
Use this reference from the response to populate paymentSession when calling /payments and /preauths from your front-end client.
See Making a Transaction﻿.
The following parameters need to remain consistent between the /paymentsession requests and the /payments and /preauths requests, otherwise the transaction will fail:
YourPaymentReference
YourConsumerReference
JudoID
Currency
Amount
This is used to cross reference the validity of the transaction.
﻿
Step Two: Add the Payment Form to your Website
﻿
﻿
Create and customise the Judopay Web SDK iFrame
﻿
An example of an iFrameConfiguration object:
iFrame Configuration Object Example
//Script to create a minimum iframe:
<script>
const iFrameConfiguration = {
    isGeoLocationGatheringAllowed: true, 
    iframe: {
    language: "en", 
    errorFieldId: 'judopay-errors', 
    showCardTypeIcons: true, 
    layout: "vertical", 
    cardTypeIconRight: "10px", 
    cardTypeIconTop: "-2px",
    backgroundColor: "#FFFFFF", 
    enabledPaymentMethods: ['CARD'], 
    defaultCountryCode: 'UK',
    isCountryAndPostcodeVisible: false, 
    isCardHolderNameVisible: true, 
    errorsDisplay: "HIDE_UNDER_FIELDS", 
    disableUnderline: false, 
    shouldAutofocus: true, 
            }
    }
</script>
//Script to create a minimum iframe:
<script>
const iFrameConfiguration = {
    isGeoLocationGatheringAllowed: true, 
    iframe: {
    language: "en", 
    errorFieldId: 'judopay-errors', 
    showCardTypeIcons: true, 
    layout: "vertical", 
    cardTypeIconRight: "10px", 
    cardTypeIconTop: "-2px",
    backgroundColor: "#FFFFFF", 
    enabledPaymentMethods: ['CARD'], 
    defaultCountryCode: 'UK',
    isCountryAndPostcodeVisible: false, 
    isCardHolderNameVisible: true, 
    errorsDisplay: "HIDE_UNDER_FIELDS", 
    disableUnderline: false, 
    shouldAutofocus: true, 
            }
    }
</script>
﻿
The iframe is created in your <SCRIPT> location.
See below for more details on the parameters that create the iFrameConfiguration object:
Parameter
Description
isGeoLocationGatheringAllowed
Boolean
isGeoLocationGatheringAllowed = false
The browser will not ask for the location.
isChallengeModalCancelButtonVisible
Boolean
isChallengeModalCancelButtonVisible = true
If set to false, the cancel (X) button on the 3D Secure 2 challenge modal will not be shown.
iFrame Parameters:
﻿
language
String
﻿
Sets the language of the iFrame.
Values:
en (english) (Default)
es (spanish)
fr (french)
pt (portugese)
de (german)
errorFieldId
String
﻿
Set as the class name of the <div> where the errors appear.
For example:
<div class="judopay-errors">Error Location</div>
showCardTypeIcons
Boolean
﻿
showCardTypeIcons = true
The card icons will display when the card entry is recognised.
cardTypeIconRight
String
Changes the position of the card icon.
cardTypeIconTop
String
Changes the position of the card icon.
backgroundColor
String
﻿
Sets the background colour of the iFrame.
For example:
#FFFFFF
Default: white
layout
String
﻿
Sets the layout of the iFrame payment form.
Values:
vertical (default)
compact
horizontal
For the form layout illustrations, see  Form Layout﻿.
defaultCountryCode
String
﻿
Sets the country displayed in the country field.
For example:
UK
isCountryAndPostcodeVisible
Boolean
﻿
isCountryAndPostcodeVisible = true
The country and postCode fields will be displayed.
isCardHolderNameVisible
Boolean
isCardHolderNameVisible = true
The cardHolderName field will be displayed.
enabledPaymentMethods
String [ ]
﻿
Array of accepted payment methods.
Values:
CARD
IDEAL
errorsDisplay
String
﻿
Formats how errors are displayed to the consumer.
Values:
SHOW_ALL
HIDE_UNDER_FIELDS
HIDE_UNDER_FORM
HIDE_ALL
shouldAutofocus
Boolean
﻿
shouldAutofocus = true
Sets the focus to the cardNumber field when the iFrame appears
idealPollingTimeout
Number
﻿
Specifies the amount of time the system waits for the IDEAL alternative payment method to respond.
For example: 6000
disableUnderline
Boolean
﻿
disableUnderline = false
When the consumer enters information into the iFrame, the fields will be underlined and highlighted.
allowedCardSchemes
String [ ]
﻿
Array of accepted card schemes.
If this field is set, an error will appear if an unsupported card scheme is entered.
Values:
amex
mastercard
maestro
visa
diners
discover
jcb
styles
Object
﻿
A JSON object.
Define further css style customisation for the payment fields.
For more information, see Styles Properties﻿.
fonts
Object [ ]
﻿
An array of JSON objects, each representing a font.
For more information, see Form Fonts﻿.
﻿
Payment Methods
Once the paymentSession﻿ and payment iFrame﻿ steps have been implemented, you can integrate the below payment methods, using our Web SDK:
Card Payments
﻿Creating a Payment / PreAuth Request﻿ 
﻿Token Payment Request﻿ 
﻿CheckCard Request﻿ 
﻿SaveCard Request﻿ 
Wallet Payments
﻿Apple Pay™ for Web﻿ 
﻿Google Pay™ for Web﻿ 
Alternative Payments
﻿PayPal﻿ (BETA)﻿
﻿Klarna﻿ (BETA)﻿
﻿iDEAL﻿ 
﻿
Setting up an Incremental Authorisation
The incremental authorisation feature allows you to increment the value of your original preAuth for scenarios where you need to charge your customer a higher total amount.
By incrementing the preAuth value, you will be able to capture the total amount that you wish to charge your customer when you are ready.
The allow increment flag allows you to set up your initial preAuth so that it can be incremented by an additional amount.
This feature is only available with a limited set of processors - please check with your account manager before you use this feature.
allowIncrement is a part of the main JudoPaymentConfiguration config object, and can be set when creating the configuration object.
If present = it is automatically applied for preAuth requests.
If no value is provided = then false is set by default.
Example:
val configuration: JudoPaymentConfiguration = {
 ...
 allowIncrement: true,
};

const judopay = new JudoPay()
judopay.createCardDetails('jupay-payment-iframe', configuration)
﻿
Putting it all together to display the payment form and make a transaction:
Example Flow
<html>
<head>
    <!-- Include JudoPay WebSDK -->
    <script src="https://web.judopay.com/js/0.0/judopay.min.js"></script>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
</head>
<body>

    <!-- Where the Judopay iFrame will be displayed -->
    <div id="payment-iframe" width="100%"></div>

    <!-- Payment button for submitting iFrame input -->
    <button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>

    <!-- Where the payment form errors will be shown -->
    <div class="judopay-errors" style="color:red"></div>

    <script>

        // Define config object for customizing style/behaviour of iFrame
        const iFrameConfiguration = {
            isGeoLocationGatheringAllowed: true,
            iframe: {
                language: "en",
                errorFieldId: 'judopay-errors',
                showCardTypeIcons: true,
                layout: "vertical",
                cardTypeIconRight: "10px",
                cardTypeIconTop: "-2px",
                backgroundColor: "#FFFFFF",
                enabledPaymentMethods: ['CARD'],
                defaultCountryCode: 'UK',
                isCountryAndPostcodeVisible: false,
                isCardHolderNameVisible: true,
                errorsDisplay: "HIDE_UNDER_FIELDS",
                disableUnderline: false,
                shouldAutofocus: true,
            }
        }

        // Initializing/creating an instance of the Judopay webSDK
        var judo = new JudoPay("yourAPIToken", true);

        // Displaying the card entry iFrame
        var payment = judo.createCardDetails("payment-iframe", iFrameConfiguration);

        //Define config object for payment/preauth
        const paymentConfiguration = {
            judoId: "yourJudoId",
            amount: 1.01,
            currency: "GBP",
            phoneCountryCode: "44",
            challengeRequestIndicator: "challengeAsMandate",
            initialRecurringPayment: false,
            yourConsumerReference: "yourConsumerReference",
            yourPaymentReference: "yourPaymentReference",
            billingAddress: {
                address1: "My house",
                address2: "My street",
                town: "My town",
                postCode: "TR14 8PA",
                country: "826"
            },
            mobileNumber: "07999999999",
            emailAddress: "[email protected]"
        }

        function handleSuccess(response) {
            //Redirect to success page and handle response
        }
        function handleError(error) {
            //Redirect to error page and handle error
        }

        //Called when payment button pressed to invoke payment
        function handlePaymentButtonClick() {
            judo.invokePayment("yourPaymentSession", paymentConfiguration)
                .then(handleSuccess)
                .catch(handleError)
        }
    </script>

</body>
<html>
<head>
    <!-- Include JudoPay WebSDK -->
    <script src="https://web.judopay.com/js/0.0/judopay.min.js"></script>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
</head>
<body>

    <!-- Where the Judopay iFrame will be displayed -->
    <div id="payment-iframe" width="100%"></div>

    <!-- Payment button for submitting iFrame input -->
    <button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>

    <!-- Where the payment form errors will be shown -->
    <div class="judopay-errors" style="color:red"></div>

    <script>

        // Define config object for customizing style/behaviour of iFrame
        const iFrameConfiguration = {
            isGeoLocationGatheringAllowed: true,
            iframe: {
                language: "en",
                errorFieldId: 'judopay-errors',
                showCardTypeIcons: true,
                layout: "vertical",
                cardTypeIconRight: "10px",
                cardTypeIconTop: "-2px",
                backgroundColor: "#FFFFFF",
                enabledPaymentMethods: ['CARD'],
                defaultCountryCode: 'UK',
                isCountryAndPostcodeVisible: false,
                isCardHolderNameVisible: true,
                errorsDisplay: "HIDE_UNDER_FIELDS",
                disableUnderline: false,
                shouldAutofocus: true,
            }
        }

        // Initializing/creating an instance of the Judopay webSDK
        var judo = new JudoPay("yourAPIToken", true);

        // Displaying the card entry iFrame
        var payment = judo.createCardDetails("payment-iframe", iFrameConfiguration);

        //Define config object for payment/preauth
        const paymentConfiguration = {
            judoId: "yourJudoId",
            amount: 1.01,
            currency: "GBP",
            phoneCountryCode: "44",
            challengeRequestIndicator: "challengeAsMandate",
            initialRecurringPayment: false,
            yourConsumerReference: "yourConsumerReference",
            yourPaymentReference: "yourPaymentReference",
            billingAddress: {
                address1: "My house",
                address2: "My street",
                town: "My town",
                postCode: "TR14 8PA",
                country: "826"
            },
            mobileNumber: "07999999999",
            emailAddress: "contact@judopay.com"
        }

        function handleSuccess(response) {
            //Redirect to success page and handle response
        }
        function handleError(error) {
            //Redirect to error page and handle error
        }

        //Called when payment button pressed to invoke payment
        function handlePaymentButtonClick() {
            judo.invokePayment("yourPaymentSession", paymentConfiguration)
                .then(handleSuccess)
                .catch(handleError)
        }
    </script>

</body>
﻿
﻿
Handle the Response
﻿
﻿
﻿
﻿
Testing your Integration
Follow our Testing your Web SDK Integration﻿ test scenarios, to test your integration and generate:
Successful payments
Declined payments
Unexpected errors
﻿

Parameter	Description
isGeoLocationGatheringAllowed Boolean	isGeoLocationGatheringAllowed = false The browser will not ask for the location.
isChallengeModalCancelButtonVisible Boolean	isChallengeModalCancelButtonVisible = true If set to false, the cancel (X) button on the 3D Secure 2 challenge modal will not be shown.
iFrame Parameters:
language String	Sets the language of the iFrame. Values: en (english) (Default) es (spanish) fr (french) pt (portugese) de (german)
errorFieldId String	Set as the class name of the <div> where the errors appear. For example: <div class="judopay-errors">Error Location</div>
showCardTypeIcons Boolean	showCardTypeIcons = true The card icons will display when the card entry is recognised.
cardTypeIconRight String	Changes the position of the card icon.
cardTypeIconTop String	Changes the position of the card icon.
backgroundColor String	Sets the background colour of the iFrame. For example: #FFFFFF Default: white
layout String	Sets the layout of the iFrame payment form. Values: vertical (default) compact horizontal For the form layout illustrations, see Form Layout.
defaultCountryCode String	Sets the country displayed in the country field. For example: UK
isCountryAndPostcodeVisible Boolean	isCountryAndPostcodeVisible = true The country and postCode fields will be displayed.
isCardHolderNameVisible Boolean	isCardHolderNameVisible = true The cardHolderName field will be displayed.
enabledPaymentMethods String [ ]	Array of accepted payment methods. Values: CARD IDEAL
errorsDisplay String	Formats how errors are displayed to the consumer. Values: SHOW_ALL HIDE_UNDER_FIELDS HIDE_UNDER_FORM HIDE_ALL
shouldAutofocus Boolean	shouldAutofocus = true Sets the focus to the cardNumber field when the iFrame appears
idealPollingTimeout Number	Specifies the amount of time the system waits for the IDEAL alternative payment method to respond. For example: 6000
disableUnderline Boolean	disableUnderline = false When the consumer enters information into the iFrame, the fields will be underlined and highlighted.
allowedCardSchemes String [ ]	Array of accepted card schemes. If this field is set, an error will appear if an unsupported card scheme is entered. Values: amex mastercard maestro visa diners discover jcb
styles Object	A JSON object. Define further css style customisation for the payment fields. For more information, see Styles Properties.
fonts Object [ ]	An array of JSON objects, each representing a font. For more information, see Form Fonts.

Updated 25 Sep 2024

Web Integrations

Payment Request