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.

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.

    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.

    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:

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

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.

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.

    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.

    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:

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

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.

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

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