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 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 docid\ uuvcdjxtcajyqhd4xfpye 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 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 ideal 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 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 parameter description judoid string required required unique id supplied by judopay specific to a merchant and/or location format 100100100 maximum length 9 characters do not include spaces or dashes amount decimal required required the amount to process format two decimal places for currencies using a different structure please contact judopay for support currency string required required the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur yourconsumerreference string required required unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string required required your unique reference for this payment format maximum length 50 characters 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 optional the country code of the consumer's phone format maximum length 3 characters only numbers allowed do not include special characters or spaces should be set if mobilenumber is set if not set, default = 44 mobilenumber string optional optional consumer’s valid mobile number format maximum length 15 characters only numbers allowed do not include special characters or spaces must be set if phonecountrycode is set cardholdername string optional 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 optional indicates the type of challenge request you wish to apply set this to one of the following strings nopreference nochallenge no challenge required challengepreferred a challenge is preferred for this transaction challengeasmandate must challenge this transaction this should not be included in the same configuration object as scaexemption scaexemption string optional optional to apply for an exemption from sca, for a customer initiated transaction set this to one of the following strings lowvalue transactions up to €45 do not require sca, up to a maximum of five consecutive transactions, or a cumulative limit of €100 securecorporate request exemption for payments made using a corporate card trustedbeneficiary provides the cardholder the option to add the merchant to their trusted list transactionriskanalysis allows for certain remote transactions to be exempt from sca, provided a robust risk analysis is performed this should not be included in the same configuration object as challengerequestindicator initialrecurringpayment boolean optional optional indicates if this initial payment is part of a recurring payment billingaddress object optional optional card holder's billing address properties address1 address2 (optional) town state (only required if country is usa/canada) format string iso alpha 2 code (e g california = " ca ") country format string see country codes docid\ xze369mfk5uvosanzm8uo for the list of valid iso 3166 1 format country codes postcode if the billingaddress is provided, the postcode is required emailaddress string optional optional consumer’s valid email address it is recommended but not required for 3d secure 2 authentication primaryaccountdetails object optional optional this is this is mandatory for merchants who have an mcc code of 6012 properties name this is the surname accountnumber postcode delayedauthorisation boolean optional 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 the default value = false 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