.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 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.

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 for more information.

Check Card

Ensure your account supports the Check Card functionality. Contact Developer Support for more details.

When making Token Payments, you can obtain the card token from the Check Card response.

Create an instance of the CheckCard Model:

//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 = "[email protected]",
    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.

*Mastercard Recommends: These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, Mastercard Recommended 3D Secure 2 Fieldsdd.

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 Recommended *	The country code of the consumer's phone. Format: Maximum length 3 characters. Only numbers allowed. Do not include special characters or spaces. Must be set if mobileNumber is set. If not set, default = 44
mobileNumber String Recommended *	Consumer’s valid mobile number. Mastercard recommends providing at least one contact method for Mastercard 3D Secure authenticated transactions. Format: Maximum length 15 characters. Only numbers allowed. Do not include special characters or spaces. Must be set if phoneCountryCode is set.
cardHolderName String Recommended *	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 (Recommended)* 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 for the list of valid ISO 3166-1 format country codes. postCode If the billingAddress is provided, the postcode is required.
emailAddress String Recommended *	Consumer’s valid email address. Mastercard recommends providing at least one contact method for Mastercard 3D Secure authenticated transactions.

If result.HasError = false, check the Payment Receipt Model response.

Save Card

Use saveCard to save the consumer's card details in Judopay's card vault.

When making Token Payments, you can obtain the card token from the Save Card response.

Create an instance of the SaveCardModel:

//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;
    }
}

*Mastercard Recommends: These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, Mastercard Recommended 3D Secure 2 Fieldsdd.

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 Recommended *	Card holder's address. Values: address1 (Recommended)* address2 (optional) town state (only required if country is USA/Canada) country See here for the list of valid ISO 3166-1 format country codes. postcode If the cardAddress is provided, the postcode is required.
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 Recommended *	The card name of the consumer.

If result.HasError = false, check the Payment Receipt Model 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:

//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 = "[email protected]",
    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;
    }
}

*Mastercard Recommends: These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, Mastercard Recommended 3D Secure 2 Fieldsdd.

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 (Recommended)* address2 (optional) town state (only required if country is USA/Canada) country See here 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 response.

Creating a PreAuth

Create an instance of the CardPayment Model:

//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 = "[email protected]",
    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;
    }
}

*Mastercard Recommends: These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, Mastercard Recommended 3D Secure 2 Fieldsdd.

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 Recommended *	The country code of the consumer's phone. Format: Maximum length 3 characters. Only numbers allowed. Do not include special characters or spaces. Must be set if mobileNumber is set. If not set, default = 44
mobileNumber String Recommended *	Consumer’s valid mobile number. Mastercard recommends providing at least one contact method for Mastercard 3D Secure authenticated transactions. Format: Maximum length 15 characters. Only numbers allowed. Do not include special characters or spaces. Must be set if phoneCountryCode is set.
cardHolderName String Recommended *	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 (Recommended)* 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 for the list of valid ISO 3166-1 format country codes. postCode If the billingAddress is provided, the postcode is required.
emailAddress String Recommended *	Consumer’s valid email address. Mastercard recommends providing at least one contact method for Mastercard 3D Secure authenticated transactions.
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.

If result.HasError = false, check the Payment Receipt Model 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, prepare the collection:

// 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 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:

// 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 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 MerchantsApplicable Merchants.

For these merchants, additional data must be included in the payment sessionpayment session and payment requests to ensure transactions are processed in line with scheme and acquirer requirements. For more information, see Account Funding Transactions.

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.

//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 = "[email protected]",
    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;
    }
}

*Mastercard Recommends: These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, Mastercard Recommended 3D Secure 2 Fieldsdd.

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 Recommended *	The country code of the consumer's phone. Format: Maximum length 3 characters. Only numbers allowed. Do not include special characters or spaces. Must be set if mobileNumber is set. If not set, default = 44
mobileNumber String Recommended *	Consumer’s valid mobile number. Mastercard recommends providing at least one contact method for Mastercard 3D Secure authenticated transactions. Format: Maximum length 15 characters. Only numbers allowed. Do not include special characters or spaces. Must be set if phoneCountryCode is set.
cardHolderName String Recommended *	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 (Recommended)* 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 for the list of valid ISO 3166-1 format country codes. postCode If the billingAddress is provided, the postcode is required.
emailAddress String Recommended *	Consumer’s valid email address. Mastercard recommends providing at least one contact method for Mastercard 3D Secure authenticated transactions.
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.

If result.HasError = false, check the Payment Receipt Model 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.

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, just needs the following additional 3D Secure 2 parameters to be included:

// 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;
}

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.

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

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 response.

Payment Receipt

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:

// 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 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

//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.

.NET Integration

Integration

Setup

Check Card

Save Card

Token Payments

Creating a PreAuth

Creating a Collection

Voiding a PreAuth Transaction

Creating a Payment

Account Funding Transactions

3D Secure 2 Transaction Flow

Additional 3D Secure 2 Parameters

ResumeThreeDSecureTwo Model Parameters

CompleteThreeDSecureTwo Model Parameters

Payment Receipt

Payment Receipt Model Parameters

Creating a Refund

Going Live