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

card security code

will be submitted by your customers into fields hosted by Judopay.

Web SDK Video Tutorials

>>> Click to learn the basics of accepting payments with our 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.

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

The following steps are prerequisites for all the payment methods available for integration using Judopay's Web SDK.

Step One: Create a paymentSession

Make sure you are using Judopay's API version 6.0.0.0 or higher.

Important to Consider

The paymentSession can be used for up to three transaction attempts for the same transaction.

If the block duplicate transactions permission has been applied on your API tokens, the paymentSession can only be used for one transaction attempt.

If you want to have this permission removed, contact Customer Support.

A payment session can be used again to re-submit a failed transaction attempt.

Once a transaction attempt is successful, the paymentSession can no longer be used even if there are any remaining attempts available.

The paymentSession will expire in 30 minutes, unless an ExpiryDate is set in the /paymentsession request body.

The expiry date must be within one year: "ExpiryDate": "2028-10-06T17:43:21+01:00"

As soon as the payment session is used for the initial transaction attempt, this will initiate the 30 minute expiry time.

To create a paymentSession:

Make a HTTP POST Request: /paymentsession

Merchants operating in specific money movement and financial services categories, as defined by the card schemes must include additional data in the payment sessionpayment session. For more information, see Account Funding Transactions.

{
  "judoId": "100100100",
  "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
  "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134",
  "currency": "GBP",
  "amount": 10.99,
  "expiryDate": "2028-02-05T16:28:32.8596+00:00" //if not set, session will expire in 30 minutes
}

For the full schema details and descriptions, see Transaction API: /paymentsession

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

Add the code snippet in your web page <HEAD>: scriptsrc="https://web.judopay.com/js/0.1.0/judopay.min.js"> This example will use jQuery for a promise, so include the following in your web page <HEAD>: <scriptsrc="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js></script>

In your <BODY> add a <div> tag where you want the iframe to appear: <div id="payment-iframe" width="100%"></div> This example uses the id: payment-frame. You can use whatever id you wish.

In your <BODY> add a <div> tag where you want the errors in form entry to appear. For the purpose of this exercise, the class is named judopay-errors, and sets a style to be red. You can add any custom style you wish in your .CSS file: <div class="judopay-errors" style="color:red">Error Location</div>

For more information on all errors that can be returned, see Payment Form Error Messages.

In your <BODY> add a button call: submit-payment-button for the iframe submission to Judopay. Make sure you have set: id="submit-payment-button" This is required to perform form validation where the Pay button will be greyed out until all the information has been entered. <button id="submit-payment-button" Pay Now </button>

You can apply any css styling you wish to this button.

In your <BODY> define the iFrameConfiguration object. This is used to customise the look and behaviour of the iFrame. For more information on customising the iFrame, see Customising your Web SDK Integration.

Create an instance of the Judopay Web SDK: var judo = new JudoPay("yourAPIToken", true); //initialize library

Alter yourAPIToken to match your Sandbox API Token

The second parameter is called useSandbox

Set to true to use the Sandbox environment.

Set to false to use the Production environment.

Create the iFrame in the <div> tag: var payment = judo.createCardDetails('payment-iFrame', iFrameConfiguration)

'payment-iFrame' The <div> id where the iFrame will be rendered, in step (2) above.

iFrameConfiguration The object defined to customise the look and behaviour of the iFrame, in step (5) above.

An example of an iFrameConfiguration object:

//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
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)

Setting up an Incremental Authorisation

The incremental authorisation feature allows you to increment the value of your original pre-authorisation for scenarios where you need to charge your customer a higher total amount.

By incrementing the pre-authorisation value, you will be able to capture the total amount that you wish to charge your customer when you are ready.

This feature is not available with all acquirers. Check with our customer service team, or your account manager for your eligibility to use this.

The allowIncrement flag is a part of the main JudoPaymentConfiguration config object, and can be set when creating the configuration object.

Set the allowIncrement flag to true.

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('judopay-payment-iframe', configuration)

Putting it all together

Putting it all together to display the payment form and make a transaction:

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

Handle the Response

All the Judopay Web SDK transaction methods return a promise. Once the authorisation is complete, the promise will be either fulfilled or rejected.

Fulfilled

You will receive a JSON object response (a Judopay receipt object).
- For more information and schema on the JSON object, see API Transaction Response.
Depending on the result the consumer should be redirected to the appropriate outcome page.
- For example, if the result = SUCCESS redirect the consumer to the Success Page.
This page should display the necessary transaction information (found in the Judopay receipt object).

Rejected

You will receive an error object
- For more information on error responses returned, see Web SDK Error Responses.
The consumer should be redirected to an Error Page.

const onFulfillment = (receiptObject) => {
  const { result } = receiptObject
  //redirect to appropriate page depending on the result (success/failure/declined page)
}

const onRejection = (error) => {
  //redirect to error page and handle error
}

For more information on the response codes, see Codes.

Voiding an Incremental Authorisation Transaction

Each incremental authorisation generates its own receiptId.

If an authorisation has been incremented, any subsequent void request must reference the receiptId of the original pre-authorisation transaction.

Using the receiptId returned following an incremental authorisation will result in an error.

The void amount must be the sum of the original authorisation amount and all successful increments. Any attempt to process a partial void, the sum of any but not all authorisations and increments, will result in an error.

For example:

Initial preAuth: £100

incrementalAuth request amount: £20

incrementalAuth request amount: £30

Total authorised amount after increments: £150

To void this transaction:

Use the receiptId of the Initial preAuth.

Submit a void request for £150.

Customisation and Displaying Payment Form Error Messages

For more information on:

Customising your Web SDK integration, see Customisation
Displaying payment form error messages, see Payment Form Error Messages

Testing your Integration

Follow our Testing your Web SDK Integration test scenarios, to test your integration and generate:

Successful payments

Declined payments

Unexpected errors