Judopay Documentation

Server SDK - .NET

For examples on integrating with the .NET Server SDK, see our sample app for more information.

Integration

  1. From Visual Studio launch NuGet Package Manager

  2. Search for JudoPay.Net 

  3. Add JudoPay.Net via

    1. GUI, or

    2. Package Manager Console 

  4. Add the JudoPay.Net package:

    Install-Package JudoPay.Net

Setup

  1. Ensure all integration steps are completed

  2. Add your app’s sandbox Token and Secret:

    var client = JudoPaymentsFactory.Create(
                    JudoEnvironment.Sandbox,
                        <yourApiToken>, 
                        <yourApiSecret> 
                     );
    

    Caution

    Only sandbox API tokens and secrets will work in the sandbox.

    Using the wrong tokens and secrets will result in an authorisation failure.

  3. Ensure the SDK is configured for the sandbox environment.

  4. Use the test cards provided in the Judopay Portal:

    • Tools > Generating transactions

Tip

If performing transactions only from your backend, enable the Register Card Transactions permission for your app.

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.

Register Card

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

Note

When making a token payment, you can obtain the card token from the Register Card response.

  1. Create an instance of the RegisterCardModel:

var register = new RegisterCardModel
    { 
        JudoId = "yourJudoId", 
        YourConsumerReference = "yourUniqueReference", 
        YourPaymentReference = "yourPaymentReference", 
        CardNumber = "4906000780007612", 
        ExpiryDate = "12/25", 
        CV2 = "452", 
        CardAddress = new CardAddressModel 
        { 
            PostCode = "postCode" 
        } 
};

Note

You do not need to set an amount. This is automatically set by Judpay's API in order to register the card.

The receipt response will show the payment: Type = PreAuth.

RegisterCardModel Parameters:

Parameter

Description

YourConsumerReference

String

Required

Unique reference to anonymously identify your customer.

Advisable to use GUIDs.

Must be below 40 characters.

YourPaymentReference

String

Required

Judopay's Server SDK sets this value automatically.

If you insert a value, the SDK will change it.

This value is unique in order to protect your customers against duplicate transactions. 

YourPaymentMetaData

IDictionary

Optional

Additional information associated with a transaction to help reconcile.

JudoId

String

Required

Unique ID supplied by Judopay.

Specific to a merchant and/or location.

Format:

  • 100100100

  • Maximum length 9 characters.

  • Do not include spaces or dashes.

CardNumber

String

Required

Submitted without whitespace or non-numeric characters.

Currency

String

Optional

The currency of the transaction. Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

CV2

String

Required

The 3 or 4 digit number on the back of a credit card.

Also known as the card verification value (CVV) or security code.

StartDate

String

Optional

For Maestro cards:

Format: 

  • MM/YY

ExpiryDate

String

Optional

The expiry date of the card.

Format: 

  • MM/YY

IssueNumber

Integer

Optional

For Maestro cards:

  • A number between 1 and 2 digits (from 0 to 99).

  • Located on the front of the card.

InitialRecurringPayment

Boolean

Optional

Indicates if this initial payment is part of a recurring payment.

RecurringPayment

Boolean

Optional

Indicates if this is a recurring payment.

RelatedReceiptId

String

Optional

The receiptId returned from the first subscription payment.

Adding the relatedReceiptId references the subsequent recurring transactions to the original transaction.

  1. Send the register request to Judopay:

    var result = await 
    client.RegisterCards.Create(register);
    if (!result.HasError)
    
    {
        var receipt = result.Response as PaymentReceiptModel;
    }
  2. If result.HasError = false, check the paymentReceipt response.

Token Payments

Note

You can create a token payment following a: Payment | PreAuth | Register Card operation, as a card token is always returned.

  1. Create an instance of the TokenPaymentModel:

    var tokenPayment = new TokenPaymentModel()
        {
            JudoId = judoId,
            YourConsumerReference = receipt.Consumer.YourConsumerReference,
            Amount = 25,
            CV2 = "452",
            CardToken = receipt.CardDetails.CardToken
        };    
    

    TokenPayment Model Parameters:

    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.

    Must be below 40 characters.

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

    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.

  2. Send the request to Judopay using the token received from the RegisterCard response:

    var Receipt = await client.Payments.Create(tokenPayment);
  3. Check the paymentReceipt response.

Creating a Payment

Tip

When handling exceptions, it is good practice to use Try Catch Block.

  1. Create an instance of the CardPayment Model:

    var payment = new CardPaymentModel
      {
           JudoId = "yourJudoId",
           YourConsumerReference = "yourUniqueReference",
           YourPaymentReference = "yourPaymentReference",
           Amount = 25,
           CardNumber = "1236358700088456",
           CV2 = "341",
           ExpiryDate = "12/25",
           CardAddress = new CardAddressModel
          {
             PostCode = "postCode"
           }
        };
    

    CardPayment Model Parameters:

    Parameter

    Description

    YourConsumerReference String

    Required

    Unique reference to anonymously identify your customer.

    Advisable to use GUIDs.

    Must be below 40 characters.

    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.

    CardNumber

    String

    Required

    Submitted without whitespace or non-numeric characters.

    Currency

    String

    Optional

    The currency of the transaction. 

    Any ISO 4217 alphabetic currency code:

    • GBP

    • USD

    • EUR

    CV2

    String

    Required

    The 3 or 4 digit number on the back of a credit card.

    Also known as the card verification value (CVV) or security code.

    PrimaryAccountDetails

    Object

    Optional

    Primary Account Holder Details:

    • Name

    • AccountNumber

    • DateOfBirth

    • PostCode

    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.

    InitialRecurringPayment Boolean

    Optional

    Indicates if this initial payment is part of a recurring payment.

    RecurringPayment

    Boolean

    Optional

    Indicates if this is a recurring payment.

    Note: If recurringPayment = true, remember to send the recurringPaymentType.

    RecurringPaymentType

    enum

    Optional

    Type of recurring payment.

    Values:

    • RECURRING

      Scheduled regular payment.

    • MIT (Merchant Initiated Transaction)

      Unscheduled regular payment.

    Note: recurringPaymentType is required if recurringPayment = true.

    RelatedReceiptId

    String

    Optional

    The receiptId returned from the first subscription payment.

    Adding the relatedReceiptId references the subsequent recurring transactions to the original transaction.

    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.

    CardAddress

    Object

    Optional

    Card holder address.

  2. Send the payment to Judopay:

    var response = await client.Payments.Create(payment);
  3. If response.HasError = true. check the error content:

    {
    Code = 403
    Message = "Sorry, but we were unable to authenticate your request. Please check your details and try again."
    Category = 1
    }

    If response.HasError = false, check the paymentReceipt 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 What is Strong Customer Authentication?

  1. The instance of the CardPaymentModel you created for Creating a Payment, just needs the following additional 3D Secure 2 parameters to be included:

var paymentModel = new CardPaymentModel()
{  
    ...,
    CardHolderName = "CHALLENGE",
    MobileNumber = "07999999999",
    PhoneCountryCode = "44",
    EmailAddress = "contact@judopay.com",
    ThreeDSecure = new ThreeDSecureTwoModel
    {
        AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser
    }
};

Parameter

Description

cardHolderName

String

Required

The full name of the card holder.

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

Required

Consumer’s valid UK mobile number.

PhoneCountryCode

String

Required

The country code of the consumer's phone.

emailAddress

String

Required

Consumer’s valid email address.

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

MethodNotificationUrl

The URL that will receive the method completion message, confirming the Issuer has completed the device details check.

Format:

  • URL

  • Length: 1-256 characters

ChallengeNotificationUrl

The URL that will receive the outcome of the challenge request to the consumer.

Format:

  • URL

  • Length: 1-256 characters

  1. Send the 3D Secure 2 transaction request to Judopay:

var result = await client.Payments.Create(paymentModel);
  1. Check the response. For the purpose of this exercise the challenge response has been returned, requesting: "Additional device data is needed for 3D Secure 2":

    Note

    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.

{
  "Response": {
    "ThreeDSecure": {
      "methodUrl": "https://example.com/pay-sim/sim/acs",
      "version": "2.1.0",
      "md": "ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYjNjY2IxYWItZTk5"
    },
    "receiptId": "68869013641206075392",
    "message": "Issuer ACS has requested additional device data gathering",
    "result": "Additional device data is needed for 3D Secure 2"
  },
  
}
  1. Once the additional device data has been collected, create an instance of the ResumeThreeDSecureTwo Model:

var resumeModel = new ResumeThreeDSecureTwoModel()
{
    CV2 = "452",
    MethodCompletion = MethodCompletion.Yes
};

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.

MethodCompletion

enum

Required

Indicates if the 3DS ACS method to collect the device details was completed successfully.

Values:

  • Unknown

  • Yes

  • No

  • Unavailable

  1. Resume the transaction flow to Judopay:

    Caution

    Use the ReceiptId from the original response.

var resumeResult = await client.ThreeDs.Resume3DSecureTwo(result.Response.ReceiptId, resumeModel);
  1. Check the response. For the purpose of this exercise, the completion response has been returned, requesting: "Challenge completion is needed for 3D Secure 2":

    Note

    If no additional transaction checks are required, you will receive the usual paymentReceipt response.

    If additional transaction checks are required, you will receive the completion response.

{
  "Response": {
    "ThreeDSecure": {
      "challengeUrl": "https://example.com/challenge/brw/acs",
      "version": "2.1.0",
      "md": "ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYjNjY2IxYWItZTk5"
    },
    "receiptId": "68869013641206075392",
    "message": "Issuer ACS has responded with a Challenge URL",
    "result": "Challenge completion is needed for 3D Secure 2"
  },
}
  1. Create an instance of the CompleteThreeDSecureTwo Model:

var completeModel = new CompleteThreeDSecureTwoModel()
{
    CV2 = "452"
};

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.

  1. Complete the transaction flow to Judopay:

var completeResult = await client.ThreeDs.Complete3DSecureTwo(result.Response.ReceiptId, completeModel);

Creating a PreAuth

  1. Create an instance of the CardPaymentModel:

           var preauth = new CardPaymentModel
                {
                    JudoId = "yourJudoId",
                    YourConsumerReference = "yourUniqueReference",
                    YourPaymentReference = "yourPaymentReference",
                    Amount = 25,
                    CardNumber = "4906000780007612",
                    CV2 = "452",
                    ExpiryDate = "12/25",
                    CardAddress = new CardAddressModel
                    {
                        PostCode = "postCode"
                    }
                };            
    

    CardPaymentModel Parameters:

    Parameter

    Description

    YourConsumerReference String

    Required

    Unique reference to anonymously identify your customer.

    Advisable to use GUIDs.

    Must be below 40 characters.

    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

    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

    Primary Account Holder Details:

    • Name

    • AccountNumber

    • DateOfBirth

    • PostCode

    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.

    InitialRecurringPayment Boolean

    Optional

    Indicates if this initial payment is part of a recurring payment.

    RecurringPayment

    Boolean

    Optional

    Indicates if this is a recurring payment.

    Note: If recurringPayment = true, remember to send the recurringPaymentType.

    RecurringPaymentType

    enum

    Optional

    Type of recurring payment.

    Values:

    • RECURRING

      Scheduled regular payment.

    • MIT (Merchant Initiated Transaction)

      Unscheduled regular payment.

    Note: recurringPaymentType is required if recurringPayment = true.

    RelatedReceiptId

    String

    Optional

    The receiptId returned from the first subscription payment.

    Adding the relatedReceiptId references the subsequent recurring transactions to the original transaction.

    CardNumber

    String

    Required

    Submitted without whitespace or non-numeric characters.

    ExpiryDate

    String

    Optional

    The expiry date of the card.

    Format: 

    • MM/YY

    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.

    CardAddress

    Object

    Optional

    Card holder address.

  2. Send the preauth to Judopay:

    var preauthResult = await client.PreAuths.Create(preauth);
  3. If the preauthResult.response = successful collect the preauth amount:

    if (!result.HasError)
      {
         var collection = new CollectionModel()
             {
              ReceiptId = result.Response.ReceiptId,
              Amount = 20
               };                
    var collectionResponse = await client.Collections.Create(collection);
      }
    

    Note

    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.

  4. Check the paymentReceipt response.

Creating a Refund

You can process a full or partial refund.

Note

Ensure the Refund Payments permission is enabled on your API token.

  1. Create a refund request:

    var refund = new RefundModel()
    {
        ReceiptId = result.Response.ReceiptId,
        Amount = 20
    };
    

    RefundModel Request Parameters:

    Parameter

    Description

    ReceiptId

    String

    Required

    Judopay’s reference for the transaction. 

    Required for you to process the refund.

    Amount

    Decimal

    Required

    The amount to process. 

    Format:

    • Two decimal places

    For currencies using a different structure please contact Judopay for support

    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.

  2. Send the refund request to Judopay:

    result = await client.Refunds.Create(refund);
  3. If response.HasError = false, check the paymentReceipt response.

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

  • Register

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

Note: This field will not be included for Refund and PreAuth transaction types.

amountCollected

Decimal

Amount collected.

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

  • cardQualifier

  • cardCountry

  • bank

consumer

Object

Details of the consumer.

Used for repeat transactions.

Details:

  • consumerToken

  • 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

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.

Going Live with .Net

Use the live environment for testing before deploying your app.

Note

You will need to have tested your app in the sandbox environment before going live.

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

2. Point to the Live Environment

  • In JudoPaymentsFactory.Create method change the environment from Sandbox to Live:

    var client = JudoPaymentsFactory.Create(JudoEnvironment.Live, "YOUR_API_TOKEN", "YOUR_API_SECRET");

  • 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

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

  • Test all payment scenarios and security features to verify the expected behaviour