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 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 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 https //help\@judopay com 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 introduction docid\ s 8hoamytkgy13t0p657 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 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 quick start /#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 to automatically receive non breaking changes, you can pin to the minor version (0 0) rather than the current patch version ( 0 0 45 ) 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 true false 297false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type 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 "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 true false 250false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type 2\ in a function, add the invokepayment call this will invoke a payment using the paymentsession and paymentconfiguration invoke payment example 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 onclick attribute to the payment button \<div> \<button id="submit payment button" onclick="handlepaymentbuttonclick()"> pay now \</button> step four 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 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> testing and customising your integration for more information, see testing web sdk card payments docid\ a33b4pwt6brofejpghdh2 for more information on customising your integration, see customisation docid\ fvh6jg8c0jc7q7oc9uoac