Deprecated Integration Methods

php server sdk integration we no longer support the php sdk and it is now deprecated prerequisites php 5 5 and above composer package manager integration using the composer package manager add the judopay package to your composer json file "require" {"judopay/judopay sdk" "5 1 0"} execute $ composer install make the judopay sdk classes available to your application, by adding the following to your file require 'vendor/autoload php'; only sandbox api tokens and secrets will work in the sandbox using the wrong tokens and secrets will result in an authorisation failure setup ensure all integration steps are completed add your app’s sandbox token and secret var client = judopaymentsfactory create( judoenvironment sandbox, \<yourapitoken>, \<yourapisecret> ); ensure the sdk is configured for the sandbox environment use the test cards provided in the judopay portal tools > generating transactions create a separate app for your backend with the make payments permission enabled test all your required payment types in the sandbox environment before going live create a new judopay object, with your api credentials $judopay = new \judopay( array( 'apitoken' => 'your token', 'apisecret' => 'your secret', 'judoid' => 'your judo id', //set to true on production, defaults to false which is the sandbox 'useproduction' => false ) ); ensure the sdk is configured for the environment you are targeting for example, if you are using the sandbox environment 'useproduction' => false for the purpose of this exercise, the sandbox token and secret have been added the server sdk allows for further configuration logging to help debug you can attach a logger library validation error details can be found in the modelerrors array for example if a required field is missing from the model other payment methods using the server sdks to send payment requests with the wallet details from apple pay™ and google pay™, see our transaction api docid\ bcxnm5keok nlnrztafut for more information check card when making token payments docid 3g7a0raxglg9aic4vcwp , you can obtain the card token from the check card response create an instance of the checkcard model php //prepare the checkcard request $checkcardrequest = $judopay >getmodel('checkcard'); $checkcardrequest >setattributevalues( array( 'judoid' => 'yourjudoid', 'yourconsumerreference' => 'yourconsumerreference', 'yourpaymentreference' => 'yourpaymentreference', 'cardnumber' => '4976000000003436', 'expirydate' => '12/30', 'cv2' => '452', 'cardaddress' => array( 'address1' => '41 luke st', 'postcode' => 'ec2a 4dp', 'town' => 'london', 'countrycode' => 826 ), // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ), // following are for 3ds2 transactions 'phonecountrycode' => '44', 'mobilenumber' => '7999123456', 'emailaddress' => 'test user\@judopay com', 'cardholdername' => 'john smith', 'threedsecure' => array( 'authenticationsource' => 'browser', 'challengerequestindicator' => 'challengeasmandate', 'methodnotificationurl' => 'https //yourmethodnotificationurl', 'challengenotificationurl' => 'https //yourmethodnotificationurl' ) ) ); try { //send the request to judopay $response = $checkcardrequest >create(); if ($response\['methodurl']) { // device details are required post md as threedsmethoddata to methodurl $methodurl = $response\['methodurl']; $md = $response\['md']; } else if ($response\['challengeurl']) { // challenge is required post creq to challengeurl $challengeurl = $response\['challengeurl']; $creq = $response\['creq']; } else { $receiptid = $response\['receiptid']; if ($response\['result'] == 'success') { $cardtoken = $response\['carddetails']\['cardtoken']; } } } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } you do not need to set an amount this is automatically set by judopay's transaction api in order to check the card parameter description judoid string \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 yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string \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\ 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\ 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\ 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\ 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\ 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 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\ indicates if this initial payment is part of a recurring payment billingaddress object \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 here 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\ consumer’s valid email address it is recommended but not required for 3d secure 2 authentication if result haserror = false , check the payment receipt model docid 3g7a0raxglg9aic4vcwp response save card use savecard to save the consumer's card details in judopay's card vault when making token payments docid 3g7a0raxglg9aic4vcwp , you can obtain the card token from the save card response create an instance of the savecardmodel php //prepare the savecard request $savecardrequest = $judopay >getmodel('savecard'); $savecardrequest >setattributevalues( array( 'judoid' => 'yourjudoid', 'yourconsumerreference' => 'yourconsumerreference', 'cardnumber' => '4976000000003436', 'expirydate' => '12/30' ) ); try { //send the request to judopay $response = $savecardrequest >create(); $receiptid = $response\['receiptid']; if ($response\['result'] == 'success') { $cardtoken = $response\['carddetails']\['cardtoken']; } } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description cardnumber string \required\ submitted without whitespace or non numeric characters expirydate string \optional\ the expiry date of the card format mm/yy cardaddress object \optional\ card holder address startdate string \optional\ for maestro cards format mm/yy issuenumber integer \optional\ for maestro cards a number between 1 and 2 digits (from 0 to 99) located on the front of the card yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters judoid string \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 currency string \optional\ the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur cardholdername string \required\ the card name of the consumer if result haserror = false , check the payment receipt model docid 3g7a0raxglg9aic4vcwp response token payments you can create a token payment following a payment | preauth | save card operation, as a card token is always returned create an instance of the tokenpaymentmodel php //prepare the tokenpayment request $tokenpaymentrequest = $judopay >getmodel('tokenpayment'); $tokenpaymentrequest >setattributevalues( array( 'judoid' => 'yourjudoid', 'yourconsumerreference' => 'yourconsumerreference', 'yourpaymentreference' => 'yourpaymentreference', 'cardtoken' => 'cardtokenfromprevioustransaction', 'cv2' => '452', 'amount' => 1 01, 'currency' => 'gbp', // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ), // following are for 3ds2 customer initiated transactions 'phonecountrycode' => '44', 'mobilenumber' => '7999123456', 'emailaddress' => 'test user\@judopay com', 'cardholdername' => 'john smith', 'threedsecure' => array( 'authenticationsource' => 'browser', 'challengerequestindicator' => 'challengeasmandate', 'methodnotificationurl' => 'https //yourmethodnotificationurl', 'challengenotificationurl' => 'https //yourmethodnotificationurl' ), // following are for merchant initiated transactions 'recurringpayment' => true, 'recurringpaymenttype' => 'mit', // unscheduled, use recurring for scheduled payments 'relatedreceiptid' => 'receiptidoforiginalcustomerinitiatedtransaction' ) ); try { //send the request to judopay $response = $tokenpaymentrequest >create(); if ($response\['methodurl']) { // device details are required post md as threedsmethoddata to methodurl $methodurl = $response\['methodurl']; $md = $response\['md']; } else if ($response\['challengeurl']) { // challenge is required post creq to challengeurl $challengeurl = $response\['challengeurl']; $creq = $response\['creq']; } else { $receiptid = $response\['receiptid']; if ($response\['result'] == 'success') { $cardtoken = $response\['carddetails']\['cardtoken']; } } } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description cardtoken string \required\ save the cardtoken into your database to send back to judopay, instead of inserting the consumer's card details yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids this must match the original yourconsumerreference when the token was initially created yourpaymentreference string \required\ set 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 yourpaymentmetadata idictionary \optional\ additional information associated with a transaction to help reconcile judoid string \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\ the amount to process format two decimal places for currencies using a different structure please contact judopay for support currency string \optional\ the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur useragent string \optional\ consumer's browser details devicecategory string \optional\ the type of device where the consumer is carrying out the transaction mobile acceptheaders string \optional\ consumer's browser details cardaddress object \optional\ card holder's billing address values address1 address2 (optional) town state (only required if country is usa/canada) country see here docid\ xze369mfk5uvosanzm8uo for the list of valid iso 3166 1 format country codes postcode if the billingaddress is provided, the postcode is required initialrecurringpayment boolean \optional\ indicates if this initial payment is part of a recurring payment recurringpayment boolean \optional\ indicates if this is a recurring payment recurringpaymenttype enum \optional\ type of recurring payment values recurring scheduled regular payment mit (merchant initiated transaction) unscheduled regular payment if a value is not set, the default value = recurring relatedreceiptid string \optional\ the receiptid returned from the first subscription payment adding the relatedreceiptid references the subsequent recurring transactions to the original transaction if result haserror = false , check the payment receipt model docid 3g7a0raxglg9aic4vcwp response creating a preauth create an instance of the cardpayment model php //prepare the preauth request $preauthrequest = $judopay >getmodel('preauth'); $preauthrequest >setattributevalues( array( 'judoid' => 'yourjudoid', 'yourconsumerreference' => 'yourconsumerreference', 'yourpaymentreference' => 'yourpaymentreference', 'cardnumber' => '4976000000003436', 'expirydate' => '12/30', 'cv2' => '452', 'amount' => 1 01, 'currency' => 'gbp', 'cardaddress' => array( 'address1' => '41 luke st', 'postcode' => 'ec2a 4dp', 'town' => 'london', 'countrycode' => 826 ), // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ), // following are for 3ds2 transactions 'phonecountrycode' => '44', 'mobilenumber' => '7999123456', 'emailaddress' => 'test user\@judopay com', 'cardholdername' => 'john smith', 'threedsecure' => array( 'authenticationsource' => 'browser', 'challengerequestindicator' => 'challengeasmandate', 'methodnotificationurl' => 'https //yourmethodnotificationurl', 'challengenotificationurl' => 'https //yourmethodnotificationurl' ) ) ); try { //send the request to judopay $response = $preauthrequest >create(); if ($response\['methodurl']) { // device details are required post md as threedsmethoddata to methodurl $methodurl = $response\['methodurl']; $md = $response\['md']; } else if ($response\['challengeurl']) { // challenge is required post creq to challengeurl $challengeurl = $response\['challengeurl']; $creq = $response\['creq']; } else { $receiptid = $response\['receiptid']; if ($response\['result'] == 'success') { $cardtoken = $response\['carddetails']\['cardtoken']; } } } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description judoid string \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\ the amount to process format two decimal places for currencies using a different structure please contact judopay for support currency string \required\ the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string \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\ 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\ 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\ 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\ 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\ 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 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\ indicates if this initial payment is part of a recurring payment billingaddress object \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 here 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\ consumer’s valid email address it is recommended but not required for 3d secure 2 authentication primaryaccountdetails object \optional\ this is mandatory for merchants who have an mcc code of 6012 , 6051 and 7299 properties name this is the surname accountnumber postcode dateofbirth format yyyy mm dd businessapplicationid string \optional\ required for aft transactions identifies the type / purpose of the transaction format maximum 2 characters values aa – account to account fd – funds disbursement ft – funds transfer pd – payroll tu – top up wt – digital wallet account type indicates the recipient's account type select from the following values 00 other 01 trn & ban 02 iban 03 card (first6 & last4) 06 ban & bic (swift code) note if businessapplicationid is provided, aftrecipientinformation must also be provided aftrecipientinformation object \optional\ required for aft transactions contains recipient details note if aftrecipientinformation is provided, businessapplicationid must also be provided values firstname recipient’s first name addressline1 recipient’s address line 1 countrycode iso 3166 1 alpha 2 country code accounttype type of recipient account accountid unique identifier of the recipient account for more information, see account funding transactions docid 5ol ptsgbhvgkwjwd0ghg if result haserror = false , check the payment receipt model docid 3g7a0raxglg9aic4vcwp response creating a collection partial collections are supported use the same receiptid to collect different amounts up to the original preauth amount you cannot collect more than the original amount following the preauth docid 3g7a0raxglg9aic4vcwp , prepare the collection php //prepare the collection request $collectionrequest = $judopay >getmodel('collection'); $collectionrequest >setattributevalues( array( 'receiptid' => 'yourpreauthreceiptid', 'yourpaymentreference' => 'yourcollectionreference', 'amount' => 1 01 ) ); try { //send the request to judopay $response = $collectionrequest >create(); $receiptid = $response\['receiptid']; $status = $response\['result']; } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description receiptid string \required\ judopay's reference for the pre authorisation that is to be collected amount decimal \required\ the amount to collect must not exceed the amount of the original pre authorisation format two decimal places for currencies using a different structure please contact judopay for support currency string \required\ if specified, the currency must match the original pre authorisation if not specified, the currency of the original pre authorisation will be used any iso 4217 alphabetic currency code gbp usd eur yourpaymentreference string \required\ your unique reference for this collection format maximum length 50 characters this is not the yourpaymentreference of the original pre authorisation yourpaymentmetadata string \optional\ key value map for additional metadata associated with this transaction will be stored but not processed or passed to gateways do not include sensitive information like card numbers check the payment receipt model docid 3g7a0raxglg9aic4vcwp response voiding a preauth transaction cancel a pre authorised transaction if the funds have not yet settled voids cannot be performed on transactions that have been collected (partial or full) create a void request php //prepare the void request $voidrequest = $judopay >getmodel('voidtransaction'); $voidrequest >setattributevalues( array( 'judoid' => 'yourjudoid', // this attribute will not be required in the next version of the sdk 'receiptid' => 'yourpreauthreceiptid', 'yourpaymentreference' => 'yourvoidreference', 'amount' => 1 01 ) ); try { //send the request to judopay $response = $voidrequest >create(); $receiptid = $response\['receiptid']; $status = $response\['result']; } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description receiptid string \required\ judopay's reference for the pre authorisation that is to be voided amount decimal \required\ the amount to void format two decimal places for currencies using a different structure please contact judopay for support currency string \required\ if specified, the currency must match the original pre authorisation if not specified, the currency of the original pre authorisation will be used any iso 4217 alphabetic currency code gbp usd eur yourpaymentreference string \required\ your unique reference for this void format maximum length 50 characters this is not the yourpaymentreference of the original pre authorisation yourpaymentmetadata string \optional\ key value map for additional metadata associated with this transaction will be stored but not processed or passed to gateways do not include sensitive information like card numbers if result haserror = false , check the payment receipt model docid 3g7a0raxglg9aic4vcwp response creating a payment create an instance of the cardpayment model php //prepare the payment request $paymentrequest = $judopay >getmodel('payment'); $paymentrequest >setattributevalues( array( 'judoid' => 'yourjudoid', 'yourconsumerreference' => 'yourconsumerreference', 'yourpaymentreference' => 'yourpaymentreference', 'cardnumber' => '4976000000003436', 'expirydate' => '12/30', 'cv2' => '452', 'amount' => 1 01, 'currency' => 'gbp', 'cardaddress' => array( 'address1' => '41 luke st', 'postcode' => 'ec2a 4dp', 'town' => 'london', 'countrycode' => 826 ), // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ), // following are for 3ds2 transactions 'phonecountrycode' => '44', 'mobilenumber' => '7999123456', 'emailaddress' => 'test user\@judopay com', 'cardholdername' => 'john smith', 'threedsecure' => array( 'authenticationsource' => 'browser', 'challengerequestindicator' => 'challengeasmandate', 'methodnotificationurl' => 'https //yourmethodnotificationurl', 'challengenotificationurl' => 'https //yourmethodnotificationurl' ) ) ); try { //send the request to judopay $response = $paymentrequest >create(); if ($response\['methodurl']) { // device details are required post md as threedsmethoddata to methodurl $methodurl = $response\['methodurl']; $md = $response\['md']; } else if ($response\['challengeurl']) { // challenge is required post creq to challengeurl $challengeurl = $response\['challengeurl']; $creq = $response\['creq']; } else { $receiptid = $response\['receiptid']; if ($response\['result'] == 'success') { $cardtoken = $response\['carddetails']\['cardtoken']; } } } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description judoid string \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\ the amount to process format two decimal places for currencies using a different structure please contact judopay for support currency string \required\ the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string \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\ 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\ 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\ 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\ 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\ 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 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\ indicates if this initial payment is part of a recurring payment billingaddress object \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 here 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\ consumer’s valid email address it is recommended but not required for 3d secure 2 authentication primaryaccountdetails object \optional\ this is mandatory for merchants who have an mcc code of 6012 , 6051 and 7299 properties name this is the surname accountnumber postcode dateofbirth format yyyy mm dd businessapplicationid string \optional\ required for aft transactions identifies the type / purpose of the transaction format maximum 2 characters values aa – account to account fd – funds disbursement ft – funds transfer pd – payroll tu – top up wt – digital wallet account type indicates the recipient's account type select from the following values 00 other 01 trn & ban 02 iban 03 card (first6 & last4) 06 ban & bic (swift code) note if businessapplicationid is provided, aftrecipientinformation must also be provided aftrecipientinformation object \optional\ required for aft transactions contains recipient details note if aftrecipientinformation is provided, businessapplicationid must also be provided values firstname recipient’s first name addressline1 recipient’s address line 1 countrycode iso 3166 1 alpha 2 country code accounttype type of recipient account accountid unique identifier of the recipient account for more information, see account funding transactions docid 5ol ptsgbhvgkwjwd0ghg if result haserror = false , check the payment receipt model docid 3g7a0raxglg9aic4vcwp response 3d secure 2 transaction flow authenticate a 3d secure 2 transaction to allow for additional transaction checks required for compliance with strong customer authentication (sca) for more information on 3d secure 2 and sca, see managing sca compliance docid\ ulg1ucayg3ljb7t0svcw5 make sure your account has 3d secure 2 api credentials enabled contact customer support to set this up the instance of the cardpaymentmodel you created for creating a payment docid 3g7a0raxglg9aic4vcwp , just needs the following additional 3d secure 2 parameters to be included php // see payment, preauth sections for details of how to trigger an initial transaction with required 3ds2 attributes // if the response indicated device details check are required, post the returned md (as an attribute named // threedsmethoddata) to the returned methodurl, and wait for a call from acs to the methodnotificationurl supplied on // the initial transaction // once the call to the methodnotificationurl has been received, resume the transaction flow to judopay $resumerequest = $judopay >getmodel('resumethreedsecuretwo'); $resumerequest >setattributevalues( array( 'receiptid' => $response\['receiptid'], // receiptid of the original transaction 'methodcompletion' => 'yes', 'cv2' => '452', // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ) ) ); try { //send the request to judopay $resumeresponse = $resumerequest >update(); if ($resumeresponse\['challengeurl']) { // challenge is required post creq to challengeurl $challengeurl = $resumeresponse\['challengeurl']; $creq = $resumeresponse\['creq']; } else { // transaction has been processed $receiptid = $response\['receiptid']; $status = $response\['result']; } } catch (\judopay\exception\apiexception $resumeapiexception) { $resumeerrorresponse = "{\\"error\\" \\"{$resumeapiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $resumevalidationerrors) { // required attributes are missing from the request $resumeerrorresponse = "{\\"error\\" \\"{$resumevalidationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $resumeexception) { $resumeerrorresponse = "{\\"error\\" \\"" $resumeexception >getmessage() "\\",\\"result\\" \\"error\\"}"; } // if either the initial transaction response, or the resume response, indicated a challenge is required, post the // returned creq to the returned challengeurl, and wait for a call from acs to the challengenotificationurl supplied on // the initial transaction // once the call to the challengenotificationurl has been received, complete the transaction flow to judopay $completerequest = $judopay>getmodel('completethreedsecuretwo'); $completerequest >setattributevalues( array( 'receiptid' => $response\['receiptid'], // receiptid of the original transaction 'cv2' => '452', // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ) ) ); try { //send the request to judopay $completeresponse = $completerequest >update(); // transaction has been processed $receiptid = $completeresponse\['receiptid']; $status = $completeresponse\['result']; } catch (\judopay\exception\apiexception $completeapiexception) { $completeerrorresponse = "{\\"error\\" \\"{$completeapiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $completevalidationerrors) { // required attributes are missing from the request $completeerrorresponse = "{\\"error\\" \\"{$completevalidationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $completeexception) { $completeerrorresponse = "{\\"error\\" \\"" $completeexception >getmessage() "\\",\\"result\\" \\"error\\"}"; } additional 3d secure 2 parameters parameter description cardholdername string \required\ the full name of the card holder when testing in the sandbox environment, it is the cardholdername that is used to determine the test card for 3d secure 2 authentication format alphanumeric length 2 45 characters allowed special characters \[ '␣] mobilenumber string \optional\ consumer’s valid uk mobile number phonecountrycode string \optional\ the country code of the consumer's phone emailaddress string \optional\ consumer’s valid email address it is recommended but not required for 3d secure 2 authentication threedsecure object \required\ for any 3d secure 2 requests authenticationsource indicates the type of channel used to initiate the transaction format enum values unknown browser merchant initiated mobile sdk challengerequestindicator indicates the type of 3d secure 2 challenge request format enum values nopreference nochallenge no challenge required challengepreferred a challenge is preferred for this transaction challengeasmandate must challenge this transaction scaexemption the customer initiated transaction type, that is exempt from sca format enum values lowvalue transactions up to €45 do not require sca, up to a maximum of five consecutive transactions, or a cumulative limit of €100 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 make sure when testing methodnotificationurl and challengenotificationurl you use a real url for the values if you use a localhost url, it will not work methodnotificationurl the url that will receive the method completion message, confirming the issuer has completed the device details check url length 1 256 characters challengenotificationurl the url that will receive the outcome of the challenge request to the consumer url length 1 256 characters if no additional transaction checks are required, you will receive the usual paymentreceipt response if additional transaction checks are required, you will receive the challenge response resumethreedsecuretwo model parameters parameter description cv2 string \required\ the 3 or 4 digit number on the back of a credit card also known as the card verification value (cvv) or security code primaryaccountdetails object \optional\ for mcc 6012, 6051 and 7299 merchants, this object needs to be added to the request without this, 3d secure 2 transactions will not be successful values name accountnumber dateofbirth postcode methodcompletion enum \required\ indicates if the 3ds acs method to collect the device details was completed successfully values unknown yes no unavailable completethreedsecuretwo model parameters parameter description cv2 string \required\ the 3 or 4 digit number on the back of a credit card also known as the card verification value (cvv) or security code primaryaccountdetails object \optional\ for mcc 6012, 6051 and 7299 merchants, this object needs to be added to the request without this, 3d secure 2 transactions will not be successful values name accountnumber dateofbirth postcode check the payment receipt model docid 3g7a0raxglg9aic4vcwp response payment receipt payment receipt model parameters parameter description receiptid string judopay's reference for the transaction used to process refunds or collections yourpaymentreference string your unique reference for this payment 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 type string type of transaction payment refund preauth collection this transaction type is available from api version 6 4 1 onwards acquirertransactionid string the unique id of a transaction set by the acquirer createdat date an iso8601 formatted date and time includes time zone offset result string result of transaction message string message detailing the outcome externalbankresponsecode string reason code provided by the bank for declined transactions judoid string unique id supplied by judopay specific to a merchant and/or location merchantname string merchant's trading name appearsonstatementas string how the merchant appears on the consumer's statement originalamount decimal amount of transaction this field will not be included for refund and preauth transaction types amountcollected decimal amount collected this field will be included for the preauth transaction type netamount decimal the remaining balance of the transaction after a refund you cannot refund more than the original transaction amount amount decimal the amount to process format two decimal places for currencies using a different structure please contact judopay for support currency string the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur carddetails object information on the card used in this transaction cardlastfour enddate cardtoken cardtype startdate cardscheme cardfunding cardcategory cardcountry bank consumer object details of the consumer used for repeat transactions details yourconsumerreference device object specific device details to identify a consumer identifier riskscore integer consumer's risk score yourpaymentmetadata string additional information associated with a transaction to help reconcile threedsecure object for any 3dsecure requests includes the result of the authentication process attempted result this block will not be returned for voids / refunds or collections responses challengerequestindicator string indicates the type of challenge request you wish to apply values nopreference nochallenge no challenge required challengepreferred a challenge is preferred for this transaction challengeasmandate must challenge this transaction scaexemption string to apply for an exemption from sca, for a customer initiated transaction values 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 risks object risk checks on postcodecheck cv2check merchantsuggestion merchantstatistics recurring boolean is the transaction a recurring transaction? if false, the field will not be returned recurringpaymenttype enum type of recurring payment values recurring scheduled regular payment mit (merchant initiated transaction) unscheduled regular payment recurringpaymenttype is required if recurringpayment = true creating a refund you can process a full or partial refund ensure the refund payments permission is enabled on your api token create a refund request php //prepare the refund request $refundrequest = $judopay >getmodel('refund'); $refundrequest >setattributevalues( array( 'receiptid' => 'yourpaymentreceiptid', 'yourpaymentreference' => 'yourrefundreference', 'amount' => 1 01 // optional, if not specified full payment amount will be refunded ) ); try { //send the request to judopay $response = $refundrequest >create(); $receiptid = $response\['receiptid']; $status = $response\['result']; } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } parameter description receiptid string \required\ judopay's reference for the transaction that is to be refunded amount decimal \required\ the amount to refund format two decimal places for currencies using a different structure please contact judopay for support currency string \required\ if specified, the currency must match the original transaction if not specified, the currency of the original transaction will be used any iso 4217 alphabetic currency code gbp usd eur yourpaymentreference string \required\ your unique reference for this refund format maximum length 50 characters this is not the yourpaymentreference of the original transaction check the payment receipt model docid 3g7a0raxglg9aic4vcwp response going live test all your required transaction types in the live environment before deploying your app you will need to have tested your app in the sandbox environment before going live activate your account to process live payments, ensure you have a live account complete the activation form for us to make the necessary changes to your account we will contact you as soon as you are live point to the live environment replace your sandbox api token and secret for the live api token and secret find these in judopay portal > your apps > { app name } > live tokens php //in the judopay object change the production environment setting from false to true 'useproduction' => true $judopay = new \judopay( array( 'apitoken' => 'your token, 'apisecret' => 'your secret', 'judoid' => 'your judo id', //set to true on production, defaults to false which is the sandbox 'useproduction' => true ) ); test live payments ensure the sdk is properly configured for the live environment use real debit or credit cards test cards provided will not work in live we recommend to perform pre authorizations followed by a void, or regular payments followed by a refund send a refund through the judopay portal > history test all payment scenarios and security features to verify the expected behaviour woocommerce plugin we are no longer supporting the woocommerce plugin this is now deprecated this version of the judopay woocommerce plugin uses judopay's web payments solution, to take online card payments as well as apple pay™ and google pay™ the plugin supports 3d secure 2 0 transactions, if the issuing bank requires prerequisites below are the versions of systems this plugin has been developed and tested on although other versions may work, they are not guaranteed wordpress version 6 8 1 woocommerce version 9 9 3 php version 8 1 2 contact developer support mailto\ developersupport\@judopay com for the woocommerce plugin file if you are not using these versions the lower versions may work but are not guaranteed judopay will not be making any modifications to accommodate lesser working versions equally, any new versions that may cause functionality to fail will be looked at on a best case scenario wordpress configuration requirement it is important that the permalink configuration within wordpress is set to post name for example https //www yourdomain com/wordpress/sample post/ ensure you are careful when changing this, if any other plugins require a different configuration this may cause issues with other plugins if you are unsure then do not use this plugin installation ensure you have woocommerce installed and working as desired go to the wordpress plugins section select add new select upload plugin click choose file locate the judopayhosted zip file, then click install now click activate plugin to activate the plugin the installation is now complete configure woocommerce in plugins for woocommerce click settings woocommerce settings click on the payments tab toggle the enabled button to enable judopay hosted gateway to configure your judopay plugin details, click manage configure the judopay plugin sandbox mode is enabled by default and will use the sandbox account when you are ready to go live and have a live account, de select enable sandbox mode to receive live payments contact your sales adviser (sales\@judopayments com) in order to set up a live transacting account debug mode will log to the wordpress log file if required this will not log card details in any way apitoken this your unique api token from your judopay account apisecret this your unique api secret from your judopay account judoid this is your unique judoid for assistance with your judopay account, contact help\@judopay com https //help\@judopay com sign up for a free sandbox account here https //www judopay com/apply sandbox account checkout view success and failure urls once the plugin is set up, login to portal judopay com and set up your success and failure urls the api token used by the plugin needs to use the following as its success / failure url https //www yoursite com/wc api/judopay webhook where yoursite com is your wordpress site this is the return url for judopay to call the woocommerce site and update the transaction status register card we are no longer supporting or updating register card as it is an outdated method to verify cards, and is now deprecated check card https //docs judopay com/net and php integrations#lubtm is the recommended card verification method required by the card schemes use registercard to save the consumer's card details in judopay's card vault when making token payments docid\ hnglljxesinhs7ptfevtn , you can obtain the card token from the register card response create an instance of the registercard model net //create an instance of the registercard model var registercardrequest = new registercardmodel { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", yourpaymentreference = "yourpaymentreference", cardnumber = "4976000000003436", expirydate = "12/25", cv2 = "452", cardaddress = new cardaddressmodel { address1 = "41 luke st", postcode = "ec2a 4dp", town = "london", countrycode = 826 }, // primaryaccountdetails only required for mcc6012 merchants primaryaccountdetails = new primaryaccountdetailsmodel { name = "smith", accountnumber = "1234567", dateofbirth = "2000 12 31", postcode = "ec2a 4dp" }, // following are for 3ds2 transactions phonecountrycode = "44", mobilenumber = "7999123456", emailaddress = "test user\@judopay com", cardholdername = "john smith", threedsecure = new threedsecuretwomodel { authenticationsource = threedsecuretwoauthenticationsource browser, challengerequestindicator = threedsecuretwochallengerequestindicator challengeasmandate, methodnotificationurl = "https //yourmethodnotificationurl", challengenotificationurl = "https //yourchallengenotificationurl" } }; //send the request to judopay var response = await client registercards create(registercardrequest); if (response haserror) { if (response error code == (int)httpstatuscode forbidden) { // failed to authenticate check your credentials } else if (response error modelerrors != null) { // validation failed on the request, check each list entry for details } else { // refer to https //docs judopay com/content/developer%20tools/codes htm#errors var errorcode = response error code; } } else if (response response is paymentrequiresthreedsecuretwomodel threedsecuretworesponsemodel) { if (threedsecuretworesponsemodel methodurl != null) { // device details are required post md as threedsmethoddata to methodurl var methodurl = threedsecuretworesponsemodel methodurl; var md = threedsecuretworesponsemodel md; } else if (threedsecuretworesponsemodel challengeurl != null) { // challenge is required post creq to challengeurl var challengeurl = threedsecuretworesponsemodel challengeurl; var creq = threedsecuretworesponsemodel creq; } } else if (response response is paymentreceiptmodel receipt) { var receiptid = receipt receiptid; var status = receipt result; if (receipt result == "success") { var cardtoken = receipt carddetails cardtoken; } } php deprecated //prepare the registercard request $registercardrequest = $judopay >getmodel('registercard'); $registercardrequest >setattributevalues( array( 'judoid' => 'yourjudoid', 'yourconsumerreference' => 'yourconsumerreference', 'yourpaymentreference' => 'yourpaymentreference', 'cardnumber' => '4976000000003436', 'expirydate' => '12/25', 'cv2' => '452', 'cardaddress' => array( 'address1' => '41 luke st', 'postcode' => 'ec2a 4dp', 'town' => 'london', 'countrycode' => 826 ), // primaryaccountdetails only required for mcc6012 merchants 'primaryaccountdetails' => array( 'name' => 'smith', 'accountnumber' => '1234567', 'dateofbirth' => '2000 12 31', 'postcode' => 'ec2a 4dp' ), // following are for 3ds2 transactions 'phonecountrycode' => '44', 'mobilenumber' => '7999123456', 'emailaddress' => 'test user\@judopay com', 'cardholdername' => 'john smith', 'threedsecure' => array( 'authenticationsource' => 'browser', 'challengerequestindicator' => 'challengeasmandate', 'methodnotificationurl' => 'https //yourmethodnotificationurl', 'challengenotificationurl' => 'https //yourmethodnotificationurl' ) ) ); try { //send the request to judopay $response = $registercardrequest >create(); if ($response\['methodurl']) { // device details are required post md as threedsmethoddata to methodurl $methodurl = $response\['methodurl']; $md = $response\['md']; } else if ($response\['challengeurl']) { // challenge is required post creq to challengeurl $challengeurl = $response\['challengeurl']; $creq = $response\['creq']; } else { $receiptid = $response\['receiptid']; if ($response\['result'] == 'success') { $cardtoken = $response\['carddetails']\['cardtoken']; } } } catch (\judopay\exception\apiexception $apiexception) { $errorresponse = "{\\"error\\" \\"{$apiexception >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\judopay\exception\validationerror $validationerrors) { // required attributes are missing from the request $errorresponse = "{\\"error\\" \\"{$validationerrors >getsummary()}\\",\\"result\\" \\"error\\"}"; } catch (\exception $e) { $errorresponse = "{\\"error\\" \\"" $e >getmessage() "\\",\\"result\\" \\"error\\"}"; } you do not need to set an amount this is automatically set by judopay's transaction api in order to register the card the receipt response will show the payment type = preauth parameter description yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string \required\ judopay's server sdk sets this value automatically if you insert a value, the sdk will change it this value is unique in order to protect your customers against duplicate transactions yourpaymentmetadata idictionary \optional\ additional information associated with a transaction to help reconcile judoid string \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 cardnumber string \required\ submitted without whitespace or non numeric characters currency string \optional\ the currency of the transaction any iso 4217 alphabetic currency code gbp usd eur cv2 string \required\ the 3 or 4 digit number on the back of a credit card also known as the card verification value (cvv) or security code startdate string \optional\ for maestro cards format mm/yy expirydate string \optional\ the expiry date of the card format mm/yy issuenumber integer \optional\ for maestro cards a number between 1 and 2 digits (from 0 to 99) located on the front of the card initialrecurringpayment boolean \optional\ indicates if this initial payment is part of a recurring payment recurringpayment boolean \optional\ indicates if this is a recurring payment relatedreceiptid string \optional\ the receiptid returned from the first subscription payment adding the relatedreceiptid references the subsequent recurring transactions to the original transaction threedsecure object \required\ for any 3d secure 2 requests authenticationsource indicates the type of channel used to initiate the transaction format enum values unknown browser merchant initiated mobile sdk challengerequestindicator indicates the type of 3d secure 2 challenge request format enum values nopreference nochallenge no challenge required challengepreferred a challenge is preferred for this transaction challengeasmandate must challenge this transaction scaexemption the customer initiated transaction type, that is exempt from sca format enum values 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 if result haserror = false , check the payment receipt model docid\ hnglljxesinhs7ptfevtn response testing registercard we are no longer supporting or updating register card as it is an outdated method to verify cards, and is now deprecated check card https //docs judopay com/net and php integrations#lubtm is the recommended card verification method required by the card schemes these scenarios do not include 3d secure 2 authentication testing see testing 3d secure 2 flows docid\ bdcgiyqdm3mle ubxp1yr for 3d secure 2 authentication testing for your app registercard scenarios (positive flow) registercard conducts a pre authorisation by reserving a pre configured amount in the customer's account the pre configured amount is set during your on boarding process ( the default amount is 1 01 ) registercard will tokenise the card information into an encrypted string, which can be used for future transactions the post /transactions/voids endpoint can be used to cancel this pre authorisation so it does not appear in the customer's statement important to consider registercard tests involve verification of the card cardnumber cardexpirydate cv2 the account is not blocked or blacklisted exists tokenises the card number into an encrypted string store yourconsumerreference and cardtoken and supply these in future card payment, preauth, or merchant initiated transaction requests a successful registercard request verifies the card with the issuer and can be authenticated using 3d secure 2, providing you with the confidence the card is valid to make future payments suggested test scenario expected outcome tip process a registercard request with the cv2/cvv security code included in the request this will check the cv2/cvv is valid for that card 200 successful the cv2 field check will be performed during the transaction process process a registercard request without the cv2/cvv security code included in the request declined the cv2 field check will not be performed during the transaction process process a registercard request with the billing address information (cardaddress block) included in the request this will validate the billing address is registered to that card 200 successful ensure the cardaddress block has the correct fields address1 address2 town postcode required countrycode see here docid\ xze369mfk5uvosanzm8uo for the list of valid iso 3166 1 format country codes example cardaddress block "cardaddress" { "address1" "cardholder house", "address2" "1 cardholder street", "address3" "cardholder area", "town" "cardholder town", "postcode" "ab1 2cd", "countrycode" 826, "state" "fl", }, to validate the card is registered to the correct post code, ensure the following permission on your sandbox api credentials is enabled enforce avs checks the default setting = disabled process a registercard request without the billing address information (cardaddress block) included in the request 200 successful for more information on api credentials and permissions, see permissions docid\ s 8hoamytkgy13t0p657 test card data to simulate a successful registercard request use the test cards docid obafnuc1umhk vihhs5d register card request parameters sandbox endpoint https //api sandbox judopay com/transactions/registercard http method post header parameters depending on how you integrate with judopay, you can authenticate requests by /paymentsession , or tokensecretauth the token and secret pair for more information, see authentication methods docid\ ylkw5coh5nqnfq3j wjk2 api version 6 25 for the latest version of the judopay transaction api, see latest version docid\ bcxnm5keok nlnrztafut content type application/json accept application/json authorization method tokensecretauth in the authorization header supply basic { authstring } example basic txpfdpdrszwmsgk4djhxetpjbts4yjq5otdkzmo7ctk1yte0oweymdg1mmy3ywyyzweyztcwymqyzgy3o replace { authstring } with base64 encoding of \api token\ (username) \colon\ api secret (password) example \mzpdkqk1mgi8v3ky\ \ \ y158n4732dfc7595a149a20381f7af2ea2e70gr6df794b8rnwc019cc5f799kk3 authorization method paymentsessionauthtoken for payment session authentication in the api token header supply the token used to authenticate the call to generate a payment session the payment session header value must also be supplied authorization method paymentsessionauthreference for payment session authentication in the payment session header supply the reference returned in the create payment session response the api token header value must also be supplied body parameters configuration property descriptions parameter description judoid string \optional\ unique id supplied by judopay specific to a merchant and/or location format 100100100 maximum length 9 characters do not include spaces or dashes cardnumber string \required\ the unique number printed on the card (13 to 19 digits depending on card type) submitted without whitespace or non numeric characters expirydate string \required\ the expiry date of the card format mm/yy cv2 string \optional\ the 3 or 4 digit number on the back of the card also known as the card verification value (cvv) or security code yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string \optional\ 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 cardholdername string \optional\ the full name of the card holder register card request example { "yourconsumerreference" "testcustomer\@example com", "yourpaymentreference" "5312b7b1 e89c 4155 971a 6e6fa3fb1e26", "judoid" "100873697", "cardnumber" "4976000000003436", "expirydate" "12/24", "cv2" "452", "cardholdername" "lonnie rath v" } response example { "receiptid" "955140933322228704", "yourpaymentreference" "5312b7b1 e89c 4155 971a 6e6fa3fb1e26", "type" "register", "createdat" "2023 03 20t16 29 07 8907+00 00", "result" "success", "message" "authcode 852549", "judoid" 100042597, "merchantname" "shodan ai routing", "appearsonstatementas" "apl /shodanairouting ", "originalamount" "1 01", "netamount" "1 01", "amount" "1 01", "currency" "gbp", "acquirertransactionid" "02448183756786407808", "externalbankresponsecode" "", "authcode" "852549", "carddetails" { "cardlastfour" "3436", "enddate" "1224", "cardtoken" "sof vjssceeee4adidgqfqpijg", "cardtype" 11, "cardscheme" "visa", "cardfunding" "debit", "cardcategory" "classic", "cardqualifier" 0, "cardcountry" "fr", "bank" "credit industriel et commercial", "cardholdername" "lonnie rath v" }, "consumer" { "consumertoken" "qlydgbomqgmswqgd", "yourconsumerreference" "testcustomer\@example com" }, "threedsecure" { "attempted" false }, "risks" { "postcodecheck" "unknown", "cv2check" "passed", "merchantsuggestion" "allow" } } registercard scenarios (negative flow) declines can occur for various reasons, it can be impossible to simulate all the negative flows in a sandbox environment important to consider how your app handles negative flows your customer's experience should a negative flow occur logic to communicate error messages customise how your app responds how to maintain application consistency follow our suggested guidelines to simulate negative scenarios, to test your app’s error handling suggested negative test scenario expected error code error description attempt to perform a registercard request using an invalid card expiry date 161 sorry, but the card expiry date must be in the future attempt to perform a registercard request using an invalid card number 196 unable to process transaction as the card number is invalid please try again with a different card attempt to perform a registercard request with an invalid cv2 74 the cv2 entered is invalid attempt to perform a registercard request with a missing cv2 the sandbox token has cv2 enabled, the registercard request has an empty cv2 field sorry, you've not supplied the 3 digit card security code please check your details and try again this is a model error docid zrsihomuew xnrq4pbtj simulate a decline using the following test card details attempt to perform a registercard decline using the following cardnumber 4221690000004963 cv2 452 expirydate 12/24 declined card declined where the codes remain fixed, the descriptions may change you should not build any error handling logic based on these descriptions integrating ideal the ideal alternative payment method for a web sdk and mobile sdk integration, has been decommissioned integrating ideal for react native to add ideal support to your payments widget set the currency code to eur (euro) set the judoid include ideal as a payment method an example of a valid ideal configuration const configuration judoconfiguration = { judoid 'myjudoid', paymentmethods judopaymentmethod ideal } const response = await judo invokepaymentmethodscreen( mode, configuration, ) once the currency and judoid are set, ideal will be available as a payment method in the payments widget integrating ideal for android to add ideal support to your payments widget, set the currency code to eur (euro) the judoid the judoid parameter can be set by calling setjudoid on the judo builder an example of a valid ideal configuration val judo = judo builder(paymentwidgettype payment methods) setjudoid("my judo id") setcurrency("eur") build() once the currency and judoid are set, ideal will be available as a payment method in the payments widget integrating ideal for ios to add ideal support to your payments widget, set currency code to eur (euro) the judoid parameter in the jpconfiguration instance an example of a valid ideal configuration configuration judoid = @"my judo id"; once the currency and judoid are set, ideal will be available as a payment method in the payments widget integrating ideal via web sdk ideal is an online payment method that enables consumers to pay through their own bank prerequisites make sure you have implemented the following prerequisites from the web sdk integration guide create a paymentsession docid 40dwe6lbub7vdkza1qydc add the payment form to your website docid 40dwe6lbub7vdkza1qydc step one add the ideal payment tab the fields referred to in this step are part of the iframe configuration object supplied in step two in the prerequisites createcarddetails() call judo createcarddetails('payment iframe', iframeconfiguration) to add the ideal payment tab ensure the array set for the enabledpaymentmethods field includes ‘ideal’ for example enabledpaymentmethods \['card', 'ideal'] transaction timeout you can alter the timeout for ideal transactions by setting the field idealpollingtimeout set it as the number of ms you want the timeout to be for example idealpollingtimeout 40000 would set the transaction timeout to 40000ms (40 seconds) if the field is not provided, the default value is 60000ms step two making an ideal transaction define the idealconfiguration object for the payment ensure the details used when creating the paymentsession match the values set in the following configuration ideal configuration example const idealconfiguration = { judoid "yourjudoid", merchantpaymentreference "yourpaymentreference", merchantconsumerreference "yourconsumerreference", currency "eur", amount 10, country "nl", accountholdername "account holder name", paymentmethod "ideal" } to successfully process an ideal transaction, the currency must be ‘ eur ’ (euros) ideal configuration parameter descriptions parameter description judoid string \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\ the amount to process format two decimal places for currencies using a different structure please contact judopay for support currency string \required\ the currency of the transaction the iso 4217 alphabetic currency code for ideal payments this must be eur yourconsumerreference string \required\ unique reference to anonymously identify your customer advisable to use guids must be below 40 characters yourpaymentreference string \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 paymentmethod string \required\ the payment method being used ensure this is set to ideal accountholdername string \required\ the name of the account holder related to this transaction country string \required\ the 2 letter iso country code from which the consumer will be paying this must be set to nl for ideal payments 2\ call getpaymentmethod() in your function that handles the payment button click for card payments (if this is not already set up, add a function to handle this) getpaymentmethod() returns information on which tab is open in the iframe call the appropriate web sdk method to trigger the correct transaction for example if the card form tab is open, getpaymentmethod will return “card” for a payment, call invokepayment() for a preauth, call invokepreauth() if the ideal tab is open, getpaymentmethod will return “ideal” call invokepaymentwithideal() get payment method example function handlepaymentbuttonclick() { const paymentmethod = judo getpaymentmethod() if(paymentmethod === 'card') { judo invokepayment(paymentsession, paymentconfiguration) then(handlesuccess) catch(handleerror) } else if(paymentmethod === 'ideal') { judo invokepaymentwithideal(paymentsession, idealconfiguration) then(handlesuccess) catch(handleerror) } } if you do not already have an event handler on your payment button to invoke the handlepaymentbuttonclick() add the onclick attribute to your payment button \<button id="submit payment button" onclick="handlepaymentbuttonclick()"> pay now \</button> 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 step three 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 api transaction response 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 web sdk error responses 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 docid zrsihomuew xnrq4pbtj integrating klarna the klarna alternative payment method for a web sdk integration, has been decommissioned integrating klarna via web sdk klarna is a payment method that allows consumers to pay for items in instalments, or at a later date this does not impact the merchant as they will receive all of the funds upfront as klarna pays the merchant in full, taking on the debt themselves prerequisites make sure you are using web sdk version 0 0 18 (or higher) make sure you have implemented the following prerequisites from the web sdk integration guide create a paymentsession docid 40dwe6lbub7vdkza1qydc add the payment form to your website docid 40dwe6lbub7vdkza1qydc the payment form iframe must be loaded onto the page in order for payments to work however displaying the form to the consumer is not required for this transaction type to hide the payment form iframe, use \<div id="payment iframe" style="position\ absolute;width 0;height 0;border 0;">\</div> to automatically receive non breaking changes, you can pin to the minor version (0 0) rather than the current patch version ( 0 0 49 ) step one display the klarna button add the klarna button to your web page add klarna button \<body> \<div id="klarna button container" >\</div> \<script> const klarnabutton = judo getklarnabutton({ backgroundcolor '#ffb3c7', borderradius 4, color '#171717', height 36, width 280, label 'pay now' }) const container = document getelementbyid("klarna button container") container append(klarnabutton) \</script> \</body> klarna button style parameter value backgroundcolor #171717 #ffffff #ffb3c7 color #ffffff #171717 label pay now pay later slice it width number height number borderradius number step two handle the klarna button make sure the following parameters are the same values as those entered in create a paymentsession docid 40dwe6lbub7vdkza1qydc , otherwise the transaction will fail merchantpaymentreference merchantconsumerreference judoid currency amount this is used to cross reference the validity of the transaction your backend server should store the paymentsession response reference returned by judopay's api use this reference from the response to populate yourpaymentsession make sure you replace the klarnaconfiguration object values with your own handle the klarna button \<script> klarnabutton onclick = handleklarnabuttonclick function handleklarnabuttonclick() { const klarnaconfiguration = { judoid "yourjudoid", currency "gbp", amount 10, country "gb", accountholdername "account holder name", merchantpaymentreference "yourpaymentreference", merchantconsumerreference "yourconsumerreference", taxamount 0 01, mobilenumber "00441895808221", emailaddress "john\@doe com", apmdata { firstname "john", lastname "doe", mobilenumber "00441895808221", billingaddress { address1 "13 new burlington st", address2 "apt 214", town "london", country "gb", postcode "w13 3bg" } }, paymentmethod "klarna" } judo invokepaymentwithklarna('yourpaymentsession', klarnaconfiguration) then(handlesuccess) catch(handleerror) } \</script> for the specific input parameters of the products variable, refer to the klarna documentation https //docs klarna com/api/api urls/#payments api create a new credit session order lines step three 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 api transaction response 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 web sdk error responses 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 docid zrsihomuew xnrq4pbtj integrating paybybankapp for react native paybybankapp payment method for react native is no longer supported and will no longer be updated integrating paybybankapp using the payments widget for react native displaying paybybankapp as a payment method to display the paybybankapp as a payment method for reactnative create a judopbbaconfiguration export interface judopbbaconfiguration { mobilenumber? string emailaddress? string appearsonstatement? string deeplinkscheme? string deeplinkurl? string } parameter description mobilenumber string consumer's mobile number sent with the transaction as an additional parameter emailaddress string consumer's email address sent with the transaction as an additional parameter appearsonstatement string sent with the transaction as an additional parameter deeplinkscheme string used in the deeplinking process to identify your app deeplinkurl string specifies the app has opened as result of a redirect from the bank app the deeplink url contains the information needed to start polling the transaction status display pbba //with the judopbbaconfiguration set, pass it to the main judoconfiguration const pbbaconfig judopbbaconfiguration = { mobilenumber "mymobilenumber", emailaddress "myemailaddress", appearsonstatement "mystatement", deeplinkscheme 'my //app' } const config judoconfiguration = { pbbaconfiguration pbbaconfig } //call the invokepaybybankapp method //handle the response try { const judo = new judopay(token, secret) const response = await judo invokepaybybankapp(config) // handle response } catch (exception) { // handle exception } deeplink scheme when the consumer invokes the paybybankapp transaction, in order to complete the transaction, the app redirects to the user's bank app when the interaction is finished, the bank app redirects back to your app via the deeplinkscheme sending a deeplinkurl the deeplink scheme has to be set manually for ios and android, via the info plist (ios) and the androidmanifest xml (android) the deeplinkurl can be used to start polling the transaction status the deeplink events can be captured with the linking package already built in reactnative check the reactnative sample app for the implementation reference once you have captured the deeplinkurl, pass it to the deeplinkurl parameter of the judopbbaconfiguration if this parameter is set once the invokepaybybankapp is called, the polling process should automatically start integrating paybybankapp directly to your app for react native not using the mobile sdk payments widget? to integrate directly to your app instead of calling invokepaybybankapp add the branded paybybankapp button add the method as a button press action expose the paybybankapp button as follows import { judopbbabutton } from 'judokit react native' \<touchableopacity onpress={this invokepaybybankapp}> \<judopbbabutton style={{ flex 1 }} /> \</touchableopacity> although, the judopbbabutton is referred to as a button, it does not handle button related events, such as onpress the judopbbabutton will need to be wrapped in a component that handles touch events, for example the touchableopacity component xamarin integration xamarin sdk has been deprecated and will no longer be updated prerequisites you have set up your judopay account sign up for your sandbox account, to receive access to your judopay dashboard and the sandbox environment your judoids and tokens are configured and enabled as appropriate for more information on permissions, see permissions you have the latest version of the android sdk for more details, see integrating android with judopay you have the latest version of the ios sdk for more details, see integrating ios with judopay for mobile apps, we recommend using payment session authentication integration requirements xamarin studio 6 1 / visual studio 2015 xamarin forms 2 3 2 127 xcode 8 android 7 0 (api 24) sdk and build tools 24 0 3 installed the sdk is compatible with android jelly bean (4 1) and above and ios 8 and above integrate judopay into your project by visiting the xamarin component store search for judopay add the component to your android and ios projects setting up xamarin ensure all integration steps are completed add your app’s sandbox token and secret to your judo instance in your xamarin forms page var judo = new judo { judoid = "\<judo id>", token = "\<api token>", secret = "\<api secret>", environment = judoenvironment sandbox, amount = 1 50m, currency = "gbp", consumerreference = "youruniquereference" }; add additional configuration depending on the project you are integrating, as follows due to a bug in xamarin forms the page does not resize correctly when the keyboard is visible an additional piece of code must be added to your android activity add the code snippet after the xamarin forms forms init method call inside the oncreate method of your activity window\ setsoftinputmode(softinput adjustresize); androidbugfix5497 assistactivity(this); xamarin forms has issues resolving dependencies using dependencyservice unless they have been registered add the following in your appdelegate cs after the loadapplication(new app()) method call in your finishedlaunching method dependencyservice register(); dependencyservice register(); // required if using apple pay dependencyservice register(); going live with xamarin you will need to have tested your app in the sandbox environment before going live point to the live environment within your app’s xamarin forms page change the line specifying the targeted environment from sandbox to live environment = judoenvironment live, replace your sandbox api token and secret for the live api token and secret apitoken = "\<api token>", apisecret = "\<api secret>", find these in judopayportal > your apps > { app name } > live tokens use the live environment for testing before deploying your app paybybankapp paybybankapp payment method is no longer supported and will no longer be updated paybybankapp is a new, easy and secure alternative payment method, that enables your consumers to pay online quickly and securely via their trusted mobile bank app paybybankapp facilitates the enablement of consumers using bank transfers to easily pay for goods and services online without the need to enter card details or additional passwords every time a purchase is made, it is designed to simplify the checkout experience, giving consumers more control and visibility of their finances when making a purchase consumer journey on a merchant's mobile app the consumer's journey on a mobile app, when selecting the paybybankapp button features of paybybankapp features of paybybankapp strong authentication psd2 compliant meeting the strong customer authentication (sca) requirements increased consumer trust existing bank brands are known to the consumer works through the consumer’s existing bank app merchant liability shifted to the issuer all transactions are authenticated via the consumers bank app, so all liability is shifted away from the merchant to the issuing bank everything is tokenised the merchant, judopay and the distributor does not have any bank details of the consumer benefits of paybybankapp to your consumers your consumers can check their balances in real time choose which account to pay from no need to enter card details, or any additional passwords can see money move from their account in seconds stay secure with payment authorisation taking place in their bank app consumers will be auto enrolled when their online bank app is installed if a consumer uses paybybankapp with more than one bank app on their phone, they will get the choice of which bank app to open at the point of purchase, with the choice of setting their default option once the consumer clicks the paybybankapp button, they will be taken to their bank app to complete the payment integrating paybybankapp android paybybankapp payment method is no longer supported and will no longer be updated to add the paybybankapp button add pbba button //insert the button in the layout file \<com judopay judokit android ui common paybybankbutton android\ id="@+id/paybybankbutton" android\ layout width="wrap content" android\ layout height="wrap content" /> //set onclicklistener to the paybybankapp button //the judoactivity will start and pass the result to merchant paybybankbutton setonclicklistener { val intent = intent(this, judoactivity class java) intent putextra(judo options, judo) startactivityforresult(intent, judo payment widget request code) } //enable the paybybankapp in the payment selector screen //build the judo configuration object //set the payment widget type to paymentwidgettype payment methods //set the currency gbp val amount = amount builder() setamount("1") setcurrency(currency gbp) build() judo builder(paymentwidgettype payment methods) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //start judoactivity with the judoconfiguration object val intent = intent(this, judoactivity class java) intent putextra(judo options, judo) startactivityforresult(intent, judo payment widget request code) for the paybybankapp button to appear in the payments widget, a banking app must already be installed the paybybankapp button is displayed to display the paybybankapp as a payment method for android display pbba as a payment method //add the intent filter to the androidmanifest xml file //this registers the deep link url \<activity android\ name=" mainactivity" android\ launchmode="singletask"> \<intent filter> \<action android\ name="android intent action view" /> \<category android\ name="android intent category default" /> \<category android\ name="android intent category browsable" /> \<data android\ scheme="your" android\ host="scheme" /> \</intent filter> \</activity> //create the judo object //set paymentwidgettype to //pay by bank app, or //payment methods //if using the payments widget //set currency\ gbp //create the pbbaconfiguration object\ set deeplinkscheme to the defined scheme in the androidmanifest xml file val pbbaconfiguration = pbbaconfiguration builder() setdeeplinkscheme("your //scheme") build() judo builder(paymentwidgettype pay by bank app) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //override the onnewintent method to catch the deeplink url //add the deeplinkurl to the pbbaconfiguration object //start judoactivity with the desired payment widget type //add the same logic in oncreate override fun onnewintent(intent intent?) { checkfordeeplink(intent) super onnewintent(intent) } override fun oncreate(savedinstancestate bundle?) { super oncreate(savedinstancestate) checkfordeeplink() } private fun checkfordeeplink(intent intent? = this intent) { val uri = intent? data val newintent = intent(this, judoactivity class java) if (uri contains("your //scheme")) { val newpbbaconfig = pbbaconfiguration newbuilder() setdeeplinkurl(uri) build() val judo = getjudo(paymentwidgettype pay by bank app) newbuilder() setpbbaconfiguration(newpbbaconfig) build() newintent putextra(judo options, judo) startactivityforresult(newintent, judo payment widget request code) } } private fun getjudo(widgettype paymentwidgettype) judo { return judo builder(widgettype) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //to catch the first response, create a broadcastreceiver private val broadcastreceiver = object broadcastreceiver() { override fun onreceive(context context?, intent intent?) { val result = intent? getparcelableextra\<judoresult>(pbba result) // handle result } } //register the defined receiver in oncreate localbroadcastmanager getinstance(this) registerreceiver( orderidreceiver, intentfilter(br pbba result) ) //catch the result in the onactivityresult method override fun onactivityresult(requestcode int, resultcode int, data intent?) { super onactivityresult(requestcode, resultcode, data) if (requestcode == judo payment widget request code) { when (resultcode) { payment success > { val result = data? getparcelableextra\<judoresult>(judo result) //process successful payment } payment cancelled > { val result = data? getparcelableextra\<judoresult>(judo result) //process cancelled payment } payment error > { val error = data? getparcelableextra\<judoerror>(judo error) //process unsuccessful payment } } } } integrating paybybankapp directly to your app for android not using the mobile sdk payments widget? to integrate directly to your app integrate pbba directly //insert the button in the layout file \<com judokit android ui common paybybankbutton android\ id="@+id/paybybankbutton" android\ layout width="wrap content" android\ layout height="wrap content" /> //add intent filter to the androidmanifest xml file //this will register the deep link url activity android\ name=" mainactivity" android\ launchmode="singletask"> \<intent filter> \<action android\ name="android intent action view" /> \<category android\ name="android intent category default" /> \<category android\ name="android intent category browsable" /> \<data android\ scheme="your" android\ host="scheme" /> \</intent filter> \</activity> //create the judo object //set the paymentwidgettype to pay by bank app //create the pbbaconfiguration object //set deeplinkscheme to the defined scheme in the androidmanifest xml file val pbbaconfiguration = pbbaconfiguration builder() setdeeplinkscheme("your //scheme") build() judo builder(paymentwidgettype pay by bank app) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //override the onnewintent method to catch the deeplink url //add the deeplinkurl to the pbbaconfiguration object //start judoactivity with the desired payment widget type //add the same logic in oncreate override fun onnewintent(intent intent?) { checkfordeeplink(intent) super onnewintent(intent) } override fun oncreate(savedinstancestate bundle?) { super oncreate(savedinstancestate) checkfordeeplink() } private fun checkfordeeplink(intent intent? = this intent) { val uri = intent? data val newintent = intent(this, judoactivity class java) if (uri contains("your //scheme")) { val newpbbaconfig = pbbaconfiguration newbuilder() setdeeplinkurl(uri) build() val judo = getjudo(paymentwidgettype pay by bank app) newbuilder() setpbbaconfiguration(newpbbaconfig) build() newintent putextra(judo options, judo) startactivityforresult(newintent, judo payment widget request code) } } private fun getjudo(widgettype paymentwidgettype) judo { return judo builder(widgettype) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //to catch the first response, create a broadcastreceiver private val broadcastreceiver = object broadcastreceiver() { override fun onreceive(context context?, intent intent?) { val result = intent? getparcelableextra\<judoresult>(pbba result) // handle result } } //register the defined receiver in oncreate localbroadcastmanager getinstance(this) registerreceiver( orderidreceiver, intentfilter(br pbba result) ) //set onclicklistener to the previously defined paybybankapp button //judoactivity will start and pass the result to merchant paybybankbutton setonclicklistener { val intent = intent(this, judoactivity class java) intent putextra(judo options, judo) startactivityforresult(intent, judo payment widget request code) } //catch the result in the onactivityresult method override fun onactivityresult(requestcode int, resultcode int, data intent?) { super onactivityresult(requestcode, resultcode, data) if (requestcode == judo payment widget request code) { when (resultcode) { payment success > { val result = data? getparcelableextra\<judoresult>(judo result) //process successful payment } payment cancelled > { val result = data? getparcelableextra\<judoresult>(judo result) //process cancelled payment } payment error > { val error = data? getparcelableextra\<judoerror>(judo error) //process unsuccessful payment } } } } \<com judokit android ui common paybybankbutton android\ id="@+id/paybybankbutton" android\ layout width="wrap content" android\ layout height="wrap content" /> //add intent filter to the androidmanifest xml file //this will register the deep link url activity android\ name=" mainactivity" android\ launchmode="singletask"> \<intent filter> \<action android\ name="android intent action view" /> \<category android\ name="android intent category default" /> \<category android\ name="android intent category browsable" /> \<data android\ scheme="your" android\ host="scheme" /> \</intent filter> \</activity> //create the judo object //set the paymentwidgettype to pay by bank app //create the pbbaconfiguration object //set deeplinkscheme to the defined scheme in the androidmanifest xml file val pbbaconfiguration = pbbaconfiguration builder() setdeeplinkscheme("your //scheme") build() judo builder(paymentwidgettype pay by bank app) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //override the onnewintent method to catch the deeplink url //add the deeplinkurl to the pbbaconfiguration object //start judoactivity with the desired payment widget type //add the same logic in oncreate override fun onnewintent(intent intent?) { checkfordeeplink(intent) super onnewintent(intent) } override fun oncreate(savedinstancestate bundle?) { super oncreate(savedinstancestate) checkfordeeplink() } private fun checkfordeeplink(intent intent? = this intent) { val uri = intent? data val newintent = intent(this, judoactivity class java) if (uri contains("your //scheme")) { val newpbbaconfig = pbbaconfiguration newbuilder() setdeeplinkurl(uri) build() val judo = getjudo(paymentwidgettype pay by bank app) newbuilder() setpbbaconfiguration(newpbbaconfig) build() newintent putextra(judo options, judo) startactivityforresult(newintent, judo payment widget request code) } } private fun getjudo(widgettype paymentwidgettype) judo { return judo builder(widgettype) setjudoid(judoid) setapitoken(token) setapisecret(secret) setamount(amount) setreference(reference) setissandboxed(issandboxed) setsupportedcardnetworks(networks) setpaymentmethods(paymentmethods) setuiconfiguration(uiconfiguration) setgooglepayconfiguration(googlepayconfiguration) setpbbaconfiguration(pbbaconfiguration) build() //to catch the first response, create a broadcastreceiver private val broadcastreceiver = object broadcastreceiver() { override fun onreceive(context context?, intent intent?) { val result = intent? getparcelableextra\<judoresult>(pbba result) // handle result } } //register the defined receiver in oncreate localbroadcastmanager getinstance(this) registerreceiver( orderidreceiver, intentfilter(br pbba result) ) //set onclicklistener to the previously defined paybybankapp button //judoactivity will start and pass the result to merchant paybybankbutton setonclicklistener { val intent = intent(this, judoactivity class java) intent putextra(judo options, judo) startactivityforresult(intent, judo payment widget request code) } //catch the result in the onactivityresult method override fun onactivityresult(requestcode int, resultcode int, data intent?) { super onactivityresult(requestcode, resultcode, data) if (requestcode == judo payment widget request code) { when (resultcode) { payment success > { val result = data? getparcelableextra\<judoresult>(judo result) //process successful payment } payment cancelled > { val result = data? getparcelableextra\<judoresult>(judo result) //process cancelled payment } payment error > { val error = data? getparcelableextra\<judoerror>(judo error) //process unsuccessful payment } } } } integrating paybybankapp ios paybybankapp payment method is no longer supported and will no longer be updated integrating paybybankapp using the payments widget for ios displaying paybybankapp as a payment method for ios to display the paybybankapp as a payment method for ios display pbba as a payment method //in the info plist of app and lsapplicationqueriesschemes add the url scheme of the merchant(cfbundleurlschemes) \<key>cfbundleurltypes\</key> \<array> \<dict> \<key>cfbundletyperole\</key> \<string>editor\</string> \<key>cfbundleurlschemes\</key> \<array> \<string>judo\</string> \</array> \</dict> \</array> \<key>lsapplicationqueriesschemes\</key> \<array> \<string>zapp\</string> \</array> //add deeplink to the pbbaconfiguration object self pbbaconfig = \[jppbbaconfiguration new]; self pbbaconfig deeplinkscheme = @"judo //pay"; //to enable the paybybankapp set the following options //add the pbba method to //the paymentmethods array in jpconfiguration //set currency gbp integrating paybybankapp directly to your app for ios not using the mobile sdk payments widget? to integrate directly to your app prerequisites "bank3 test app" contact developersupport\@judopayments com to get access, so you can test the paybybankapp flow you have set your app's url scheme you have added zapp to the applicationqueriesschemes an example of the info plist file step 1 initialising the sdk to integrate with the judopay sdk directly to your ios app, you can use either a basic authorization session authorization you can select the sandbox mode for testing purposes set the value issandboxed = true let authorization jpauthorization = jpbasicauthorization(token judo token, andsecret judo secret) judokit = judokit(authorization authorization) judokit issandboxed = true step 2 check for installed bank apps to ensure a good customer experience, it is recommended to only display the paybybankapp button when the consumer has a compatible mobile banking app before adding the paybybankapp button in step 3, check if any compatible paybybankapp bank apps are installed, using the judokit isbankingappavailable method if (judokit isbankingappavailable()) { // add the pbba button } step 3 adding the paybybankapp button we recommend you use the branded button to invoke a paybybankapp transaction, however it is not mandatory the paybybankapp button uses the delegate property the delegate property points to any class that implements the jppbbabuttondelegate interface let pbbabutton = jppbbabutton(frame container bounds); pbbabutton delegate = self view\ addsubview(pbbabutton) the jpbbabutton is a subclass of uiview , not uibutton take this into consideration when integrating the paybybankapp button via the interface builder the jppbbabuttondelegate interface has only one method pbbabuttondidpress(sender ) , which is responsible for handling the button tap action recommended paybybankapp button size minimum width 160pt | height 40pt maximum width 310pt | height 48pt step 4 adding the delegate method the delegate method is responsible for the button tap action to add the delegate method call the invokepbba method in the judopay sdk and provide the required configuration parameters invoke pbba method func pbbabuttondidpress( sender jppbbabutton) { let amount = jpamount(amount value, currency "gbp") let reference = jpreference(consumerreference consumer ref) configuration = jpconfiguration(judoid judo id, amount amount, reference reference) let pbbaconfiguration = jppbbaconfiguration() pbbaconfiguration mobilenumber = your mobile number pbbaconfiguration emailaddress = your email address pbbaconfiguration appearsonstatement = your appears on statement pbbaconfiguration deeplinkscheme = your deeplink scheme configuration pbbaconfiguration = pbbaconfiguration judokit invokepbba(with configuration) { \[weak self] (response, error) in if let response = response { // handle response } if let error = error { // handle error } } } each judopay transaction takes a jpconfiguration instance as a parameter the configuration object sets up all the required parameters for a successful transaction it also sets any optional parameters which you can configure to personalise the payment flow paybybankapp transactions require some extra parameters to be set up, in addition to the basic transaction configuration these optional parameters are defined in the jppbbaconfiguration class, and used to add additional information to the transaction the following two parameters are recommended deeplinkscheme deeplinkurl call the invokepbba method from the judopay sdk the paybybankapp flow will be triggered, opening the bank app for consumers to make their transactions the deeplinkscheme a deeplinkscheme identifies your app during the redirect process when a consumer has completed their transaction using their bank app, the bank app will attempt to redirect the consumer back to your app the deeplinkscheme name should match the url scheme defined in the info plist file for example myapp > myapp\ / the deeplinkurl the deeplink url enables the app to open the consumer's mobile banking app, so they can complete the transaction when the bank app redirects the consumer back to your app, it also provides you with a url that you can use to poll the transaction status add the deeplinkurl to the main configuration object this will be sent as a parameter to the transaction method it is a good idea to handle the errors within this step the most important information from the response is the orderid , accessed via response orderdetails orderid the orderid is used to manually check the transaction status step 5 handling the deeplinkurl following the completed transaction, the bank flow will be triggered when the invokepbba method is called, even if the deeplinkurl parameter is not provided however, if the deeplinkurl parameter is provided, calling invokepbba will trigger the transaction status polling logic to handle the deeplinkurl listen to this event capture the redirect url to capture the redirect url in your appdelegate file, add the following methods application( open\ options ) application( didfinishlaunchingwithoptions ) pass the url to the jppbbaconfiguration instance for the purpose of this exercise, the deeplinkurl is saved in the app's userdefaults you can save the deeplinkurl in the keychain or any alternative deeplink url example func application( application uiapplication, didfinishlaunchingwithoptions launchoptions \[uiapplication launchoptionskey any]? ) > bool { if let url = launchoptions?\[ url] as? url { userdefaults standard set(url, forkey "deeplinkurl") } } func application( app uiapplication, open url url, options \[uiapplication openurloptionskey any] = \[ ] ) > bool { userdefaults standard set(url, forkey "deeplinkurl") } step 6 polling the transaction status once the bank app has redirected the consumer back to your app, you can start polling the transaction status to start the paybybankapp polling status add the deeplinkurl to the configuration call the invokepbba(configuration ) method call invoke pbba method func handledeeplink() { guard let url = userdefaults standard url(forkey "deeplinkurl") else { return } configuration pbbaconfiguration? deeplinkurl = url judokit invokepbba(with configuration) { \[weak self] (response, error) in if let response = response { // handle response } if let error = error { // handle error } } } in the jpresponse object, you can inspect the orderdetails containing information about the transaction status another option is to put a check in your viewdidappear(animated ) method if a deeplinkurl is set up, add it to the configuration and call the invokepbba(configuration ) method again this will start the polling status manually checking the transaction status there may be cases where the bank app closes before the transaction flow completes this would mean the deeplinkurl is not returned and the polling process to check the transaction status will not begin to manually check the transaction status invoke a manual order status request get the orderid from the initial request when the bank app is invoked during the paybybankapp request, (step 4) the orderid is captured from the callback response response example judokit invokepbba(with configuration) { \[weak self] (response, error) in if let response = response { let orderid = response orderdetails? orderid // persist the orderid for later use } } use the orderid to manually check the transaction status you would do this in the same way as initialising the judopay sdk, see step 1 initialising the sdk call the invokeorderstatus method, with the orderid let apiservice = jpapiservice(authorization authorization, issandboxed true) apiservice invokeorderstatus(withorderid orderid) { (response, error) in // handle response } the response will contain both the transaction status, and the order details of the transaction for a sample app, see judopay's judokit for ios on github https //github com/judopay/judokit ios/tree/master/examples