Integration Steps

integrating via our transaction api this guide will take you through steps one to five, to illustrate the what is 3d secure? docid\ wpfmf662qaigegrpu mow (including the conditional steps), to verify how it relates to the user journey when integrating directly with judopay's transaction api when integrating via our web sdk docid 40dwe6lbub7vdkza1qydc and mobile sdks docid\ fyef n37tnl1c5dsscml3 , we handle the 3d secure flow, including the conditional steps on your behalf integration steps docid\ iusvpi9 6ndkb4ow4u 3c is the only step to be handled with all integration types prerequisite make sure your account has 3d secure 2 api credentials enabled contact ​customer support​​ to set this up for the back end server integration, make use of our server sdks net integration (version 3 0 0 or higher) php integration (version 5 5 or higher) or, call our api directly using json (version 6 0 0 0 or higher) step one create a payment request /payments , /preauths and /checkcard are all supported once you have the card details and device information from your client side, your back end server will need to make a payment request to judopay's transaction api the cv2 is not stored by judopay's transaction api you will need to store the cv2 for the duration of the transaction , then delete it as soon as the transaction has completed for the full /payments endpoint schema details and descriptions, see our transaction api reference here sample request net // (1) create an instance of the cardpaymentmodel var paymentmodel = new cardpaymentmodel() { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", yourpaymentreference = "yourpaymentreference", amount = 12 99, cardnumber = "1236358700088456", cv2 = "452", expirydate = "12/25", cardaddress = new cardaddressmodel { postcode = "postcode" } cardholdername = "challenge", mobilenumber = "07999999999", phonecountrycode = "44", emailaddress = "contact\@judopay com", threedsecure = new threedsecuretwomodel { authenticationsource = threedsecuretwoauthenticationsource browser, challengerequestindicator = threedsecuretwochallengerequestindicator challengeasmandate, scaexemption = threedsecuretwoscaexemption securecorporate } }; // (2) send the 3ds2 request to judopay var result = await client payments create(paymentmodel); // (3) challenge response example requesting additional device data is needed for 3d secure 2 { "response" { "threedsecure" { "methodurl" "https //example com/pay sim/sim/acs", "version" "2 1 0", "md" "ewogicj0ahjlzurtu2vydmvyvhjhbnnjrcigoiaiyjnjy2ixywitztk5" }, "receiptid" "68869013641206075392", "message" "issuer acs has requested additional device data gathering", "result" "additional device data is needed for 3d secure 2" },// (1) prepare the 3dsecure2 payment $payment = $judopay >getmodel('payment'); $attributes = \[ 'amount' => 12 99, 'cardnumber' => '4976000000003436', 'expirydate' => '12/25', 'yourconsumerreference' => 'youconsumerreference', 'yourpaymentreference' => 'yourpaymentreference', 'cv2' => '452', 'currency' => 'gbp', 'judoid' => 'yourjudoid' 'cardholdername' => 'john doe', 'mobilenumber' => '07999999999', 'phonecountrycode' => '41', 'emailaddress' => 'contact\@judopay com', 'threedsecure' => \[ 'authenticationsource' => 'browser', ] ] ]; $payment >setattributevalues($attributes); // (2) send the 3dsecure2 payment try { $cardpayment >setattributevalues($attributes); $response = $cardpayment >create(); } catch (\exception $e) { return; } // (3) check the response //challenge response example requesting additional device data is needed for 3d secure 2 { "response" { "threedsecure" { "methodurl" "https //example com/pay sim/sim/acs", "version" "2 1 0", "md" "ewogicj0ahjlzurtu2vydmvyvhjhbnnjrcigoiaiyjnjy2ixywitztk5" }, "receiptid" "68869013641206075392", "message" "issuer acs has requested additional device data gathering", "result" "additional device data is needed for 3d secure 2" },{ "cardnumber" 4111111111111111, "cv2" 452, "expirydate" "12/25", "cardaddress" { "address1" "cardholder house", "address2" "1 cardholder street", "town" "cardholder town", "postcode" "ab1 2cd", "countrycode" 826 }, "judoid" "yourjudoid", "yourconsumerreference" "yourconsumerreference", "yourpaymentreference" "yourpaymentreference", "yourpaymentmetadata" { "internallocationref" "example", "internalid" 99 }, "amount" 12 99, "currency" "gbp", "cardholdername" "john doe", "mobilenumber" 7999999999, "phonecountrycode" 44, "emailaddress" "test user\@judopay com", "shippingaddress" { "isbillingaddress" true }, "threedsecure" { "authenticationsource" "browser", "methodnotificationurl" "https //api judopay com/order/3ds/methodnotification", "challengenotificationurl" "https //api judopay com/order/3ds/challengenotification", "challengerequestindicator" "challengeasmandate" } } if no additional transaction checks are required, you will receive the usual paymentreceipt r esponse if additional transaction checks are required, you will receive the challenge response notification urls you will need to set up two endpoints for your client to receive event notifications from the issuer's acs 3ds method completion informs your client application that the acs has completed device detail gathering methodnotifcationurl acs challenge completion informs your client application that the challenge has been completed by the customer challengenotificationurl each endpoint should be configured to accept http post base64 encoded values step two (conditional) device detail gathering some issuer acs’ support device data gathering skip this step if no method url is provided in the response from the api check the response from integration steps docid\ iusvpi9 6ndkb4ow4u 3c the following fields in the response will indicate if the device details have been requested by the issuer the result field "additional device data is needed for 3d secure 2" the message field "issuer acs has requested additional device data gathering" a methodurl will be returned in the response from the initial payment request in this instance, the following steps will need to be performed render a hidden iframe on the client side targeting the methodurl rendering a hidden iframe sample open method url page 2\ post the 3ds method data ( md ) object to it the md is an encoded base 64 value containing the threedsservertransid and notificationurl as json (it is also returned in the transaction api response from integration steps docid\ iusvpi9 6ndkb4ow4u 3c 3\ listen for the redirect of the methodnotificationurl we recommend you time out after 10 seconds if you have not received a response from any notificationurls or rendered the methodurl from integration steps docid\ iusvpi9 6ndkb4ow4u 3c step three (conditional) resume transaction once the device details have been gathered, the 3d secure authentication flow needs to be resumed render a hidden iframe on the client side targeting the methodnotificationurl listen for the redirect of the methodnotificationurl where the method completion message is received resume the 3d secure flow by submitting the results of the device detail gathering for the full /resume3ds endpoint schema details and descriptions, see our transaction api reference here sample request net // (1) once the additional device data has been collected, create an instance of the resumethreedsecuretwo model var resumemodel = new resumethreedsecuretwomodel() { cv2 = "452", methodcompletion = methodcompletion no }; // (2) resume the transaction flow to judopay //use the receiptid from the original response var resumeresult = await client threeds resume3dsecuretwo(result response receiptid, resumemodel); // (1) once the additional device data has been collected, resume the transaction flow to judopay //use the receiptid from the original response resumethreedsecuretwo $resumerequest = $judopay3ds2 >getmodel('resumethreedsecuretwo'); $attributes = \[ 'receiptid' => $response\['receiptid'], 'cv2' => '452', 'methodcompletion' => 'no', ]; $resumerequest >setattributevalues($attributes); $response = $resumerequest >update(); // (1) once the device details have been gathered resume the 3d secure authentication flow { "cv2" "452", "threedsecure" { "methodcompletion" "no" } } methodcompletion value methodcompletion = yes if your client received a post to the methodnotifcationurl methodcompletion = no if your client did not receive a post to the methodnotifcationurl methodcompletion = unavailable if your client was unable to render the methodurl primaryaccountdetails block the primaryaccountdetails block is optional, however it is mandatory mandatory for merchants who have an mcc code of 6012 to submit additional information about the primary account holder for payment pre authorisation example primaryaccountdetails block "primaryaccountdetails" { "name" "smith", "accountnumber" "1234567890", "dateofbirth" "1980 01 01", "postcode" "ab1 2cd" } step four (conditional) render challenge page after you have resumed the transaction, check the response from integration steps docid\ iusvpi9 6ndkb4ow4u 3c sample response { "challengeurl" "https //mysampleapp/challenge/", "creq" "ewo8fdhjkeswujmlpsaliia6iciwmsikfq", "version" "2 1 0", "receiptid" "123456789", "result" "challenge completion is needed for 3d secure 2", "message" "issuer acs has responded with a challenge url", "md" "znkcy9tzxrob2rob3rpzmljyxrp9ojhfsik9" } the following fields in the response will indicate if your customer's bank may want to challenge the result field "challenge completion is needed for 3d secure 2" the message field "issuer acs has responded with a challenge url" a challengeurl to render the challenge page iframe for your customer render the challengeurl for your customer to complete the challenge rendering challengeurl page example sample open challenge url page creq should be set to the creq received in the response threedssessiondata can be set to contain any details you would like returned in the post listen for the redirect of the challengenotificationurl step five complete 3ds upon receiving a post back to the challengenotificationurl send a request to judopay's transaction api to complete the transaction if no additional transaction checks are required, you will receive the usual paymentreceipt response if additional transaction checks are required, you will receive the completion response for the full /complete3ds endpoint schema details and descriptions, see our transaction api reference here sample request net // (1) create an instance of the completethreedsecuretwo model var completemodel = new completethreedsecuretwomodel() { cv2 = "452", "primaryaccountdetails" { "name" "john smith", "accountnumber" "123456", "dateofbirth" "1980 01 01", "postcode" "ec2a 4dp" } }; // (2) complete the transaction flow to judopay var completeresult = await client threeds complete3dsecuretwo(result response receiptid, completemodel); completethreedsecuretwo $completerequest = $judopay3ds2 >getmodel('completethreedsecuretwo'); $attributes = \[ 'receiptid' => $response\['receiptid'], 'cv2' => '452', "primaryaccountdetails" { "name" "john smith", "accountnumber" "123456", "dateofbirth" "1980 01 01", "postcode" "ec2a 4dp" ]; $completerequest >setattributevalues($attributes); $response = $completerequest >update(); { "cv2" "452", "version" "2 0" } judopay's transaction api will respond with the both the authentication authorisation status of the transaction