Quick Start

Quickly integrate and perform a test payment with Judopay.
The following example takes you through the steps to quickly integrate and perform a test card payment using Judopay’s Web SDK.
The sample code uses PHP to directly call our API, however this can also be used as a guide in understanding how to call our API's by other methods.
Start Integrating with Judopay
To start integrating with Judopay:
Step One: Sign up for your Judopay Sandbox Account
You need your sandbox account so you can process test transactions while developing your app.
﻿
An app is a Judopay term and relates to your API credentials.
Once signed up, you will receive your:
TokenSecretAuth
The token and secret pair
Specify your token in Username and secret in Password
JudoId
Ensure Judopay has enabled 3D Secure in your sandbox account. If this is not enabled the test transaction may appear successful without following the correct payment flow.
Contact ​﻿Customer Suppor﻿t﻿​​ to set this up.
﻿
Step Two: Get Access to your Judopay Dashboard
Get access to your dashboard in the Judopay Portal where you can create your app.
For more details, see Creating your App.﻿﻿
﻿
Perform a Test Payment
The following guide is a full working example for use with Judopay's Web SDK.
When authorising /payments or /preauths it is recommended to use paymentSession.
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 /preauthsfrom your front-end client.
See Step Three: Making a Transaction.﻿﻿
The following parameters need to remain consistent between the /paymentsessionrequests 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:
﻿
﻿
Step Three: Making a Transaction
To make a transaction:
Define the paymentConfiguration object for the payment or preauth:
Ensure the details used when creating the paymentSession match the values set in the following configuration:
Payment Configuration Object Example
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]",
    primaryAccountDetails: {
        name: "Doe",
        accountNumber: "9999999",
        dateOfBirth: "1989-09-19",
        postCode: "AB1 2CD"
    }
}

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",
    primaryAccountDetails: {
        name: "Doe",
        accountNumber: "9999999",
        dateOfBirth: "1989-09-19",
        postCode: "AB1 2CD"
    }
}
﻿
﻿
Web SDK Payment Parameter Descriptions
See below for more details on the parameters that create the paymentConfiguration object:
﻿
2. In a function, add the invokePaymentcall.
This will invoke a payment using the paymentSession and paymentConfiguration
Invoke Payment Example
function handlePaymentButtonClick() {
    judo.invokePayment(paymentSession, paymentConfiguration)
    .then(handleSuccess)
    .catch(handleError)
}
function handlePaymentButtonClick() {
    judo.invokePayment(paymentSession, paymentConfiguration)
    .then(handleSuccess)
    .catch(handleError)
}
﻿
To invoke a preAuth, change the above code to .invokePreauth
3. To call the function (in step 2 above) to invoke the payment or preauth, add the onclickattribute to the payment button <div>:
<button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>
﻿
Step Four: Handle the Response
﻿
﻿
Putting it all together
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>
﻿
﻿
Testing and Customising your Integration
For more information, see Testing Web SDK - Card Payments﻿.
For more information on customising your integration, see Customising your Web SDK Integration﻿.