Web
Web Integrations
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 card security code will be submitted by your customers into fields hosted by judopay web sdk video tutorials payment flow 3ds2 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 web sdk docid 40dwe6lbub7vdkza1qydc 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" "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 payment session request 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 } response reference example //store the reference returned in your backend server { "posturl" "https //pay sandbox judopay com/v2", "reference" "5qcaaaqaaaapaaaacaaaabtggvhbrf9bhtn7nqn1e0j4hvvmi y27dgpjwbmtls3gj xdg" } for the full schema details and descriptions, see transaction api transaction api reference docid\ bcxnm5keok nlnrztafut 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 payment request docid 4dzoq07rt7fyolm0juibj 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 0 45/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 docid\ qfxawpaql 2evfp8y94d 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 customisation docid\ fvh6jg8c0jc7q7oc9uoac 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 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> 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 customisation docid\ fvh6jg8c0jc7q7oc9uoac 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 customisation docid\ fvh6jg8c0jc7q7oc9uoac fonts object \[ ] an array of json objects, each representing a font for more information, see customisation docid\ fvh6jg8c0jc7q7oc9uoac payment methods once the web sdk docid 40dwe6lbub7vdkza1qydc and web sdk docid 40dwe6lbub7vdkza1qydc steps have been implemented, you can integrate the below payment methods, using our web sdk card payments payment request docid 4dzoq07rt7fyolm0juibj token payment request docid\ vool6a4nsy9s0gyjpmbst checkcard request docid\ jsl02orbsfwqcgzg4m099 savecard request docid\ uydrryieh3ry8h7kz1zj4 wallet payments apple pay™ for web docid\ oelqjygambce2048qcjp1 google pay™ for web docid\ docx7icjrl11phchkz y alternative payments paypal docid\ rcuemk4qqk m ndm0nh8g (beta) (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 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 "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 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 transaction api reference docid\ bcxnm5keok nlnrztafut 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 payment form error messages docid\ qfxawpaql 2evfp8y94d the consumer should be redirected to an error page response example 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 and descriptions docid zrsihomuew xnrq4pbtj customisation and displaying payment form error messages for more information on customising your web sdk integration, see customisation docid\ fvh6jg8c0jc7q7oc9uoac displaying payment form error messages, see payment form error messages docid\ qfxawpaql 2evfp8y94d testing your integration follow our testing your web sdk integration docid 5tafisdj44kgccigw2z w test scenarios, to test your integration and generate successful payments declined payments unexpected errors