.NET Integration

integration from visual studio launch nuget package manager search for judopay net add judopay net via gui, or package manager console add the judopay net package install package judopay net for examples on integrating with the net server sdk, see our sample app https //github com/judopay/dotnetsdk for more information 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 for our dotnetsdk core sample app, see dotnetsdk https //github com/judopay/dotnetsdk/tree/8d5385d271aea93b1fa7b1bb04ca5546358d8c8a 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 ensure your account supports the check card functionality contact developer support mailto\ developersupport\@judopay com for more details when making token payments docid\ hnglljxesinhs7ptfevtn , you can obtain the card token from the check card response create an instance of the checkcard model net //create an instance of the checkcard model var checkcardrequest = new checkcardmodel { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", yourpaymentreference = "yourpaymentreference", cardnumber = "4976000000003436", expirydate = "12/30", cv2 = "452", cardaddress = new cardaddressmodel { address1 = "41 luke st", postcode = "ec2a 4dp", town = "london", countrycode = 826 }, // primaryaccountdetails only required for mcc6012 mcc6051 mcc7299 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 checkcards create(checkcardrequest); 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; } } 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\ hnglljxesinhs7ptfevtn response save card use savecard 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 save card response create an instance of the savecardmodel net //create an instance of the savecardmodel var savecardrequest = new savecardmodel() { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", cardnumber = "4976000000003436", expirydate = "12/30" }; //send the request to judopay var response = await client savecards create(savecardrequest); 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 paymentreceiptmodel receipt) { var receiptid = receipt receiptid; var status = receipt result; if (receipt result == "success") { var cardtoken = receipt carddetails cardtoken; } } 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\ hnglljxesinhs7ptfevtn 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 net //create an instance of the tokenpaymentmodel model var tokenpaymentrequest = new tokenpaymentmodel { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", yourpaymentreference = "yourpaymentreference", cardtoken = "cardtokenfromprevioustransaction", // cv2 only required if required by your gateway cv2 = "452", amount = 1 01m, currency = "gbp", cardaddress = new cardaddressmodel { address1 = "41 luke st", postcode = "ec2a 4dp", town = "london", countrycode = 826 }, // primaryaccountdetails only required for mcc6012 mcc6051 mcc7299 merchants primaryaccountdetails = new primaryaccountdetailsmodel { 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 = new threedsecuretwomodel { authenticationsource = threedsecuretwoauthenticationsource browser, challengerequestindicator = threedsecuretwochallengerequestindicator challengeasmandate, methodnotificationurl = "https //yourmethodnotificationurl", challengenotificationurl = "https //yourchallengenotificationurl" }, // following are for merchant initiated transactions recurringpayment = true, recurringpaymenttype = recurringpaymenttype mit, // unscheduled, use recurring for scheduled payments relatedreceiptid = "receiptidoforiginalcustomerinitiatedtransaction" }; //send the request to judopay var response = await client payments create(tokenpaymentrequest); 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; } } 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\ hnglljxesinhs7ptfevtn response creating a preauth create an instance of the cardpayment model net //create an instance of the cardpayment model var preauthrequest = new cardpaymentmodel { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", yourpaymentreference = "yourpaymentreference", cardnumber = "4976000000003436", expirydate = "12/30", cv2 = "452", amount = 1 01m, currency = "gbp", cardaddress = new cardaddressmodel { address1 = "41 luke st", postcode = "ec2a 4dp", town = "london", countrycode = 826 }, // primaryaccountdetails only required for mcc6012, mcc6051 and mcc7299 merchants primaryaccountdetails = new primaryaccountdetailsmodel { name = "smith", accountnumber = "1234567", dateofbirth = "2000 12 31", postcode = "ec2a 4dp" }, // aft fields only required for supported aft merchants // businessapplicationid and accounttype values vary by scheme and acquirer configuration businessapplicationid = "aa", aftrecipientinformation = new aftrecipientinformationmodel { firstname = "john", addressline1 = "smith house", countrycode = "gb", accountid = "5432101111", accounttype = "03" }, // 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 preauths create(preauthrequest); 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; } } 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\ hnglljxesinhs7ptfevtn 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\ hnglljxesinhs7ptfevtn , prepare the collection net // create an instance of the collection model var collectionrequest = new collectionmodel() { receiptid = yourpreauthreceiptid, amount = 1 01m // optional, if not specified full preauth amount will be collected }; //send the request to judopay var response = await client collections create(collectionrequest); 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 paymentreceiptmodel receipt) { var receiptid = receipt receiptid; var status = receipt result; } 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\ hnglljxesinhs7ptfevtn 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 net // create an instance of the void model var voidrequest = new voidmodel() { receiptid = yourpreauthreceiptid }; //send the request to judopay var response = await client voids create(voidrequest); 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 paymentreceiptmodel receipt) { var receiptid = receipt receiptid; var status = receipt result; } 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\ hnglljxesinhs7ptfevtn response creating a payment account funding transactions account funding transactions (aft) are required for merchants operating in specific money movement and financial services categories , as defined by card schemes for more information, see applicable merchants docid 5ol ptsgbhvgkwjwd0ghg for these merchants, additional data must be included in the payment session docid\ ylkw5coh5nqnfq3j wjk2 and payment requests to ensure transactions are processed in line with scheme and acquirer requirements for more information, see account funding transactions docid 5ol ptsgbhvgkwjwd0ghg to submit account funding transactions you are using judopay's api version 6 25 or higher to create a payment create an instance of the cardpayment model when handling exceptions, it is good practice to use try catch block net //create an instance of the cardpayment model var paymentrequest = new cardpaymentmodel { judoid = "yourjudoid", yourconsumerreference = "yourconsumerreference", yourpaymentreference = "yourpaymentreference", cardnumber = "4976000000003436", expirydate = "12/30", cv2 = "452", amount = 1 01m, currency = "gbp", cardaddress = new cardaddressmodel { address1 = "41 luke st", postcode = "ec2a 4dp", town = "london", countrycode = 826 }, // primaryaccountdetails only required for mcc6012, mcc6051 and mcc7299 merchants primaryaccountdetails = new primaryaccountdetailsmodel { name = "smith", accountnumber = "1234567", dateofbirth = "2000 12 31", postcode = "ec2a 4dp" }, // aft fields only required for supported aft merchants // businessapplicationid and accounttype values vary by scheme and acquirer configuration businessapplicationid = "aa", aftrecipientinformation = new aftrecipientinformationmodel { firstname = "john", addressline1 = "smith house", countrycode = "gb", accountid = "5432101111", accounttype = "03" }, // 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 payments create(paymentrequest); 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; } } 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\ hnglljxesinhs7ptfevtn 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\ hnglljxesinhs7ptfevtn , just needs the following additional 3d secure 2 parameters to be included net // 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, create an instance of the resumethreedsecuretwo model var resumethreedsrequest = new resumethreedsecuretwomodel() { methodcompletion = methodcompletion yes, cv2 = "452", // primaryaccountdetails only required for mcc6012, mcc6051 and mcc7299 merchants primaryaccountdetails = new primaryaccountdetailsmodel { name = "smith", accountnumber = "1234567", dateofbirth = "2000 12 31", postcode = "ec2a 4dp" }, }; // use the receiptid from the original transaction response var resumeresponse = await client threeds resume3dsecuretwo(result response receiptid, resumethreedsrequest); if (resumeresponse haserror) { if (resumeresponse error code == (int)httpstatuscode forbidden) { // failed to authenticate check your credentials } else if (resumeresponse 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 = resumeresponse error code; } } else if (resumeresponse response is paymentrequiresthreedsecuretwomodel resumechallengerequiredmodel) { // challenge is required post creq to challengeurl var challengeurl = resumechallengerequiredmodel challengeurl; var creq = resumechallengerequiredmodel creq; } else if (resumeresponse response is paymentreceiptmodel resumereceipt) { // transaction has been processed var receiptid = resumereceipt receiptid; var status = resumereceipt result; } // 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, create an instance of the completethreedsecuretwo // model var completethreedsrequest = new completethreedsecuretwomodel() { cv2 = "452", // primaryaccountdetails only required for mcc6051 mcc7299 mcc6012 merchants primaryaccountdetails = new primaryaccountdetailsmodel { name = "smith", accountnumber = "1234567", dateofbirth = "2000 12 31", postcode = "ec2a 4dp" } }; // use the receiptid from the original transaction response var completeresponse = await client threeds complete3dsecuretwo(result response receiptid, completethreedsrequest); if (completeresponse haserror) { if (completeresponse error code == (int)httpstatuscode forbidden) { // failed to authenticate check your credentials } else if (completeresponse 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 = completeresponse error code; } } else if (resumeresponse response is paymentreceiptmodel completereceipt) { // transaction has been processed var receiptid = completereceipt receiptid; var status = completereceipt result; } 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\ hnglljxesinhs7ptfevtn 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 net // create an instance of the refund model var refundrequest = new refundmodel() { receiptid = yourpaymentreceiptid, amount = 1 01m // optional, if not specified full payment amount will be refunded }; //send the request to judopay var response = await client refunds create(refundrequest); 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 paymentreceiptmodel receipt) { var receiptid = receipt receiptid; var status = receipt result; } 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\ hnglljxesinhs7ptfevtn 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 net //in the judopaymentsfactory create //method, change the environment from sandbox to live var client = judopaymentsfactory create(judoenvironment live, "your api token", "your api secret"); 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