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 Support 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 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": "2023-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.
-
Make a HTTP POST Request: /paymentsession
For the full schema details and descriptions, see Transaction API /paymentsession
Response Model
Payment-Session - Response Reference:
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 Step Three: 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>:
<script src="https://web.judopay.com/js/0.0.37/judopay.min.js"></script>
To automatically receive non-breaking changes, you can pin to the minor version (0.0) rather than the current patch version (0.0.37).
This example will use jQuery for a promise, so include the following in your web page <HEAD>:
<script src="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 Displaying 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.
An example of an iFrameConfiguration object:
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:
|
errorFieldId String |
Set as the class name of the <div> where the errors appear. For example:
|
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:
|
layout String |
Sets the layout of the iFrame payment form. Values:
For the form layout illustrations, see Form Layout |
defaultCountryCode String |
Sets the country displayed in the country field. For example:
|
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:
|
errorsDisplay String |
Formats how errors are displayed to the consumer. Values:
|
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:
|
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. |
- 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.
-
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:
See below for more details on the parameters that create the paymentConfiguration object:

Parameter |
Description |
---|---|
judoId String Required |
Unique ID supplied by Judopay. Specific to a merchant and/or location. Format:
|
amount Decimal Required |
The amount to process. Format:
For currencies using a different structure please contact Judopay for support. |
currency String Required |
The currency of the transaction. Any ISO 4217 alphabetic currency code:
|
yourConsumerReference String Required |
Unique reference to anonymously identify your customer. Advisable to use GUIDs. Must be below 40 characters. |
yourPaymentReference String Required |
Your unique reference for this payment. Format:
This value should be unique in order to protect your customers against duplicate transactions. With a server side integration, if a payment reference is not supplied, the transaction will not be processed. |
phoneCountryCode String Optional |
The country code of the consumer's phone. Format:
Should be set if mobileNumber is set. |
mobileNumber String Optional |
Consumer’s valid mobile number. Format:
Must be set if phoneCountryCode is set. |
cardHolderName String Optional |
The card name of the consumer.
If the cardHolderName field is displayed to the user in the payment form (isCardHolderNameVisible: true is set in the iFrame config), the value entered in the payment form will overwrite this value. |
challengeRequestIndicator String Optional |
Indicates the type of challenge request you wish to apply. Set this to one of the following strings:
This should not be included in the same configuration object as scaExemption. |
scaExemption String Optional |
To apply for an exemption from SCA, for a customer initiated transaction. Set this to one of the following strings:
This should not be included in the same configuration object as challengeRequestIndicator. |
initialRecurringPayment Boolean Optional |
Indicates if this initial payment is part of a recurring payment. |
billingAddress Object Optional |
Card holder's billing address. Properties:
If the billingAddress is provided, the postcode is required. |
emailAddress String Optional |
Consumer’s valid email address. It is recommended but not required for 3D Secure 2 authentication. |
primaryAccountDetails Object Optional |
This is Mandatory for merchants who have an MCC code of 6012 Properties:
This is the surname.
|
delayedAuthorisation Boolean Optional |
For preAuths only. Set to true to authenticate a card holder with 3D secure, without performing payment authorisation. When set to true, the 3D Secure authentication status is returned in the response.
The payment authorisation is carried out at the stage when you are ready to collect the amount from the consumer.
|
-
In a function, add the invokePayment call.
This will invoke a payment using the paymentSession and paymentConfiguration
To invoke a preauth, change the above code to .invokePreauth
-
To call the function (in step 2 above) to invoke the payment or preauth, add the onclick attribute to the payment button <div>:
<button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>
Step Four: Handle the Response
Once the authorisation is complete you will receive either:
-
A JSON object response (a Judopay receipt object)
For more information and schema on the JSON object, see API Transaction Response.
-
An error object
For more information on error responses returned, see Web SDK Error Responses.
The consumer should be redirected to the outcome screen and the response/error should be handled accordingly.
For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.
For more information on the response codes, see Codes.
Putting it all together to display the payment form and make a transaction:
Testing and Customising your Integration
For more information, see Testing your Integration.
For more information on customising your integration, see Customising your Web SDK Integration.