Web Payments

web payments is not the same as using the web sdk with judopay’s web payments solution, a minimal integration is all that is required to enable you to take a payment with 3d secure 2 built in and easily enabled, this also ensures your payments meet the managing sca compliance docid\ ulg1ucayg3ljb7t0svcw5 (sca) compliance requirement generate hosted payment page links using judopay’s transaction api and redirect the consumer back to your own website, using configured redirect urls this helps minimise your pci scope by providing consumers with a secure way to pay online via their browser, optimised for any device you can customise which screens are visible to the consumer during their payment journey for more information, see web payments /#payment journey screen customisation web payments enables the following payment methods apple pay™ google pay™ paypal (beta) (beta) as well as offering consumers the traditional pay with card payment method integrating web payments prerequisites make sure you are using judopay's api version 6 0 0 0 or higher we recommend using the latest api version to check which api version you are on, see the version value set in your api integration code (the api version http request header) we recommend setting up webhooks docid\ mqjiizxmcro1cpvauawud to notify your system with transaction status updates make sure you have set up web payments /#web payments set up for your app in the judopay portal configure the https success and failure urls (see web payments /#web payments set up below) redirections to the web payments url should utilise the http get method to align with expected behaviour and ensure best practice web payments set up web payments do not apply for mobile and your server side or mobile only integrations to set up web payments log in to the judopay portal from the side menu, select your apps select the app you wish to edit for the purpose of this exercise, document testing app is selected this configuration is to be set up for each of your web payments apps select web payments configuration the web payments configuration screen appears select the enable web payments (hosted redirect web payment) tickbox specify the success and failure urls ( depending on the transaction result, this is where the consumer will be redirected once the transaction process is completed ) note you can set up the same success and failure urls for both the sandbox and live environments for this to work as expected, when setting up web payments for your application in the judopay portal, you must create a separate application for each environment click save configuration success and failure urls should be configured using the https protocol this will prevent the browser’s pop up messages, warning the consumer of insecure connectivity web payments flow web payments payment request you can also create a web payments web payments /#web payments preauth request web payments /#web payments checkcard request the checkcard request is similar to the preauth request, just remove the amount field step one generate a web payments link make sure you are using judopay's api version 6 0 0 0 or higher to generate the web payments link c reate a web payments payment session make a http post request /paymentsession 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 enabled on your api tokens, the paymentsession can only be used for one transaction attempt to have this permission disabled , contact customer support https //help\@judopay com we recommend using a dedicated api token for web payments integrations this will avoid the possibility of duplicate transactions occuring for other integrations you can also use the following http post request https //api sandbox judopay com/webpayments/payments for the full schema details and descriptions, see transaction api transaction api reference docid\ bcxnm5keok nlnrztafut payment session request example { "judoid" "yourjudoid", "yourconsumerreference" "yourconsumerreference", "yourpaymentreference" "yourpaymentreference", "yourpaymentmetadata" { "internallocationref" "example", "internalid" 99, "hidebackbutton" true }, "currency" "gbp", "amount" 12 99, "cardaddress" { "address1" "cardholder house", "address2" "1 cardholder street", "town" "cardholder town", "postcode" "ab1 2cd", "countrycode" 826, "state" "fl", "cardholdername" "john doe" }, "expirydate" "2021 02 05t16 28 32 8596+00 00", "ispaybylink" false, "isjudoaccept" false, "successurl" "https //my site com/success", "cancelurl" "https //my site com/cancel", "emailaddress" "test user\@judopay com", "mobilenumber" "7999999999", "phonecountrycode" "44", "threedsecure" { "challengerequestindicator" "challengeasmandate" }, "hidebillinginfo" true, "hidereviewinfo" true, "primaryaccountdetails" { "name" "doe", "accountnumber" "12345678", "dateofbirth" "1980 01 31", "postcode" "ab1 2cd" } } response reference example //store the reference returned in your backend server { "paybylinkurl" "https //pay sandbox judopay com/abc123", "posturl" "https //pay sandbox judopay com/v2", "reference" "5qcaaaqaaaapaaaacaaaabtggvhbrf9bhtn7nqn1e0j4hvvmi y27dgpjwbmtls3gj xdg" } send the link url (in the response example above), to the consumer the reference has an expiration time of 30 minutes if the transaction is not completed within this time, the transaction will fail and the status = expired step two consumer submits a payment u sing the web payment reference / url generated in web payments /#step one generate a web payments link send the payment link to the consumer the consumer clicks the link, and is re directed to the payment form the payment form (which is hosted by judopay), allows the consumer to submit a payment example payment flow below is an example of a consumer's payment flow within judopay's hosted payments page the consumer is re directed to the hosted payments page the amount to pay is displayed, including all available payment methods this screen is only displayed when there are multiple payment methods offered redirections to the web payments url should utilise the http get method to align with expected behaviour and ensure best practice for the purpose of this exercise, pay with card is selected the billing information screen appears the billing information screen can be hidden, see web payments /#hide the billing information screen for moto consumers, the billing information and review & confirm screens will not be displayed the consumer will be directed straight to the pay with card screen the consumer enters their billing information entering the billing information is optional in order for the address to be used, all the mandatory fields in the billing information page must be completed by the consumer address line 1 town country see country codes docid\ xze369mfk5uvosanzm8uo for the list of valid iso 3166 1 format country codes state (if country = canada/usa) postcode tap continue the pay with card screen appears the consumer enters their card details tap continue the review & confirm screen appears the review & confirm screen can be hidden, see web payments /#hide the review confirm screen for moto consumers, the billing information and review & confirm screens will not be displayed the consumer will be directed straight to the pay with card screen tap confirm payment to pay the consumer can tap the change button to edit their card details / billing information the payment successful screen appears the payment information is displayed you can redirect the consumer to a success / cancel url, see web payments /#step three handle the response step three handle the response the consumer is redirected to the outcome screen the attributes set in the request body will determine where the consumer is redirected if "ispaybylink" false, the consumer will be directed to the success / cancel url's you set in the payload, as shown below any url configurations set in your api token , will be ignored if "ispaybylink" true , the consumer will be directed to judopay's default success / cancel screens any url configurations set in your api token , or in the payload will be ignored if "ispaybylink" false, and the urls have not been added to the request, the consumer will be directed to judopay's default success / cancel screens any url configurations set in your api token will be ignored to specify the successurl and cancelurl , see web payments /#web payments set up for more information on common error scenarios and to troubleshoot errors, see troubleshooting docid\ oz8vuw6vab40nqeq61p1r web payments preauth request use webpayments/preauths to reserve funds on a consumer's account preauths will postpone the completion of the transaction until the goods have been delivered or the service fulfilled to create a preauth request follow web payments /#web payments payment request c hange the request url to https //api sandbox judopay com/webpayments/preauths for the full schema details and descriptions, see transaction api transaction api reference docid\ bcxnm5keok nlnrztafut web payments checkcard request use webpayments/checkcard to perform a zero amount pre authorisation (0 auth) checkcard also enables you to check the validity of the card, to be used for future payments to create a checkcard request follow web payments /#web payments payment request c hange the request url to https //api sandbox judopay com/webpayments/checkcard remove the amount field from the request object for the full schema details and descriptions, see transaction api transaction api reference docid\ bcxnm5keok nlnrztafut monitoring transaction information do not confuse reference with yourpaymentreference reference push and pull information with our api yourpaymentreference a variable to track the transaction check transaction result the paymentsession can be used for up to three transaction attempts for the same transaction check the noofauthattempts field in the response to determine the number of transaction attempts send a request to our api using the reference from judopay's response make a https get request https //api sandbox judopay com/webpayments/{reference} get transaction result example //you will receive the following transaction receipt information "status" "success", "shortreference" "kyldmo", "amount" 399, "companyname" "my company", "currency" "gbp", "expirydate" "2025 12 07t18 28 32 8596+00 00", "judoid" "100013531", "paymentcancelurl" "https //judopay com", "paymentsuccessurl" "https //judopay com", "reference" "6qcaaacaaaacaaaacwaaaigf pcus9upbuk", "allowedcardtypes" \[ 1, 2, 3, 8, 10, 11, 12, 13 ], "response" { "posturl" "https //pay sandbox judopay com/v2", "reference" "6qcaaacaaaacaaaacwaaaigf pcus9upbuk" }, "transactiontype" "payment", "yourconsumerreference" "tk test 2025 07 02", "yourpaymentreference" "tk test 2025 07 02 05", "webpaymentoperation" 0, "isjudoaccept" false, "isthreedsecuretwo" true, "noofauthattempts" 1, "receipt" { "receiptid" "1257662426096709632", "yourpaymentreference" "tk test 2025 07 02 05", "type" "payment", "createdat" "2025 07 02t12 41 28 6095+01 00", "result" "success", "message" "authcode 321116", "judoid" 100013531, "merchantname" "john doe", "appearsonstatementas" "apl /johndoe ", "netamount" "399 00", "amount" "399 00", "currency" "gbp", "acquirertransactionid" "74450001183715833468", "externalbankresponsecode" "", "authcode" "321116", "postcodecheckresult" "unknown", "acquirer" "cashflows", "webpaymentreference" "6qcaaacaaaacaaaacwaaaig", "noofauthattempts" 1, "carddetails" { "cardlastfour" "3436", "enddate" "1225", "cardtoken" "sof oknnyt 4ra pcpktsqabeg", "cardtype" 11, "cardscheme" "visa", "cardfunding" "debit", "cardcategory" "", "cardcountry" "fr", "bank" "credit industriel et commercial", "cardholdername" "challenge required" }, "billingaddress" {}, "consumer" { "yourconsumerreference" "tk test 2025 07 02" }, "yourpaymentmetadata" { "customeremail" "john doe\@judopay com", "policy id" "policy001", "country origin" "pl" }, "threedsecure" { "attempted" true, "result" "passed", "challengerequestindicator" "challengeasmandate", "eci" "05" }, "risks" { "postcodecheck" "unknown", "cv2check" "passed", "eciindicator" "05", "merchantsuggestion" "allow" } } } for the full schema details and descriptions, see transaction api transaction api reference docid\ bcxnm5keok nlnrztafut we would also recommend setting up webhooks docid\ mqjiizxmcro1cpvauawud to notify your system with real time transaction status updates check the webhook message "result" field for the status for the purpose of this exercise, the following examples indicate a success and card declined webhook message scenario the webhook message will make four attempts to be delivered following this, the message will fail to deliver and be dropped to query transactions, make a https get request /transactions use the paymentreference , or consumerreference fields use the yourpaymentmetadata array to include enhanced data for each payment check transaction receipt we recommend displaying the following order information on your receipt screen date and time amount result (success or failure message) appearsonstatementas ( this will appear on your card statement as … ) 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 can be set as part of the payment session that is created when generating a web payment link for a preauth set the allowincrement flag to true this is set as part of the post /webpayments/preauths request body example { "judoid" "100100100", "yourconsumerreference" "2b45fd3f cee5 4e7e 874f 28051db65408", "yourpaymentreference" "6482c678 cad3 4efd b081 aeae7a89a134", "yourpaymentmetadata" { "internallocationref" "example", "internalid" 99 }, "currency" "gbp", "amount" 10 99, "allowincrement” true, "cardaddress" { "address1" "cardholder house", "address2" "1 cardholder street", "town" "cardholder town", "postcode" "ab1 2cd", "countrycode" "826", "cardholdername" "john doe" }, "expirydate" "2023 02 05t16 28 32 8596+00 00", "ispaybylink" true, "emailaddress" "test user\@judopay com", "mobilenumber" "7999999999", "phonecountrycode" "44", "threedsecure" { "challengerequestindicator" "challengeasmandate" } } payment journey screen customisation the web payments card payment journey consists of the following steps select payment method enter billing information (optional) enter card details review and confirm (optional) you can customise whether to display the billing information , the review & confirm screens and the back button to the consumer during their payment journey hide the billing information screen for moto consumers, the billing information screen will not be displayed the consumer will be directed straight to the pay with card screen set the hidebillinginfo flag when creating the payment session the billing information screen will be hidden create a web payment session where hidebillinginfo = true the consumer is directed to the card payment screen hide the review & confirm screen for moto consumers, the review & confirm screen will not be displayed the consumer will be directed straight to the pay with card screen set the hidereviewinfo flag when creating the payment session the review & confirm screen will be hidden create a web payment session where hidereviewinfo = true the consumer will not be directed to the review & confirm screen during the payment flow the hidebillinginfo and hidereviewinfo flags can be used in combination, by setting both flags hide the back button in the yourpaymentmetadata block, set the hidebackbutton flag to true when creating the payment session the back button will be hidden create a web payment session where hidebackbutton = true the back button will not be displayed on the landing page pre fill the billingaddress / cardholder address if you set cardaddress when creating the payment session, the billing information screen will be hidden we will use the latest address provided when processing the payment if required, the consumer can edit the address when they reach the review & confirm screen the consumer is directed to the payment method screen for the purpose of this exercise, the billing address has been supplied by the merchant when creating the payment session the consumer is directed to the card payment screen the review & confirm screen displays the address as supplied by the merchant when creating the payment session the consumer taps the change button to edit the billing information the consumer is directed to a blank billing information page the consumer edits the billing details and taps the continue button all the mandatory fields in the billing information page need to be completed by the consumer, otherwise the address will not be updated (address line 1 | town | country | (state if country = canada/usa), | postcode) see country codes docid\ xze369mfk5uvosanzm8uo for the list of valid iso 3166 1 format country codes the billing information (from step 3) has been replaced with the new address details adding payment methods you can enable alternative payment methods, as well as offering consumers the traditional pay with card payment method there is no additional integration required, just contact customer support mailto\ help\@judopay com to enable this for you testing your integration ensure the project is configured for the sandbox environment you will need your authentication methods docid\ ylkw5coh5nqnfq3j wjk2 use the test cards docid obafnuc1umhk vihhs5d provided for more information, see testing web payments card payments docid\ zv5mpxmmqxjq1rp3fayxk