--- title: .NET Integration slug: net-and-php-integrations docTags: createdAt: 2024-05-23T14:33:49.184Z --- ## Integration 1. From Visual Studio launch: **NuGet Package Manager** 2. Search for JudoPay.Net 3. Add JudoPay.Net via - GUI, or - Package Manager Console 4. 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. *** :::hint{type="warning"} Only sandbox API tokens and secrets will work in the sandbox. Using the wrong tokens and secrets will result in an **authorisation failure**. ::: ## Setup 1. Ensure all integration steps are completed. 2. Add your app’s sandbox Token and Secret: `var client = JudoPaymentsFactory.Create(` ` JudoEnvironment.Sandbox,` ` , ` ` ` `);` 3. Ensure the SDK is configured for the sandbox environment. 4. Use the test cards provided in the Judopay Portal: - **Tools** > **Generating transactions** :::hint{type="info"} 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 :::hint{type="warning"} Ensure your account supports the Check Card functionality. Contact [Developer Support](mailto\:developersupport@judopay.com) for more details. ::: :::hint{type="info"} When making [Token Payments](docId\:hNgLLJxESInHS7PtfEvTN), you can obtain the **card token** from the Check Card response. ::: **Create an instance of the CheckCard Model**: :::CodeblockTabs .NET ```apex //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; } } ``` ::: :::hint{type="info"} You do not need to set an amount. This is automatically set by Judopay's Transaction API in order to check the card. ::: :::hint{type="warning"} **\*Mastercard Recommends:** These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow). ::: | **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](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
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](docId\:hNgLLJxESInHS7PtfEvTN) response. *** ## Save Card Use `saveCard` to save the consumer's card details in Judopay's card vault. :::hint{type="info"} When making [Token Payments](docId\:hNgLLJxESInHS7PtfEvTN), you can obtain the **card token** from the Save Card response. ::: **Create an instance of the SaveCardModel**: :::CodeblockTabs .NET ```apex //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; } } ``` ::: :::hint{type="warning"} **\*Mastercard Recommends:** These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow). ::: | **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](docId\:XZE369mFK5UVOSaNzM8UO) 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](docId\:hNgLLJxESInHS7PtfEvTN) response. *** ## Token Payments :::hint{type="info"} 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**: :::CodeblockTabs .NET ```apex //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; } } ``` ::: :::hint{type="warning"} **\*Mastercard Recommends:** These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow). ::: | **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](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**: :::CodeblockTabs .NET ```apex //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; } } ``` ::: :::hint{type="warning"} **\*Mastercard Recommends:** These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow). ::: | **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](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
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](docId:5ol_pTSGBHVGKwJwD0gHg). | If **result.HasError = false**, check the [Payment Receipt Model](docId\:hNgLLJxESInHS7PtfEvTN) response. *** ## Creating a Collection :::hint{type="info"} 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**: :::CodeblockTabs .NET ```apex // 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. :::hint{type="warning"} Voids cannot be performed on transactions that have been collected (partial or full). ::: **Create a void request**: :::CodeblockTabs .NET ```apex // 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). :::hint{type="warning"} 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: :::hint{type="info"} When handling exceptions, it is good practice to use Try Catch Block. ::: :::CodeblockTabs .NET ```apex //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;     } } ``` ::: :::hint{type="warning"} **\*Mastercard Recommends:** These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow). ::: | **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](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
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](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). :::hint{type="warning"} 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: :::CodeblockTabs .NET ```apex // 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; } ``` ::: :::ExpandableHeading ### 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. :::ExpandableHeading ### 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 | ::: :::ExpandableHeading ### 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 :::ExpandableHeading ### 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. :::hint{type="warning"} Ensure the **Refund Payments** permission is enabled on your API token. ::: **Create a refund request**: :::CodeblockTabs .NET ```apex // 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. :::hint{type="warning"} You will need to have tested your app in the sandbox environment before going live. ::: :::::WorkflowBlock :::WorkflowBlockItem 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. ::: ::::WorkflowBlockItem 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** :::CodeblockTabs .NET ```apex //In the: JudoPaymentsFactory.Create //method, change the environment from Sandbox to Live: var client = JudoPaymentsFactory.Create(JudoEnvironment.Live, "YOUR_API_TOKEN", "YOUR_API_SECRET"); ``` ::: :::: :::WorkflowBlockItem 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. ::: :::::