Server SDKs

.NET Integration

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

 

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> 
);

Only sandbox API tokens and secrets will work in the sandbox.
Using the wrong tokens and secrets will result in an authorisation failure.

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

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

    • Tools > Generating transactions

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.

For our DotNetSDK core sample app, see DotNetSDK.

 

PHP Integration

Prerequisites

  • PHP 5.5 and above

  • Composer Package Manager

 

Integration

Using the Composer Package Manager:

  1. Add the Judopay package to your composer.json file:

"require": {        
"judopay/judopay-sdk": "5.1.0"}

  1. Execute: $ composer install

  2. Make the Judopay SDK classes available to your application, by adding the following to your file: require 'vendor/autoload.php';

 

Setup

  1. Create a new Judopay object, with your API credentials:

$judopay = new \Judopay(
    array(
        'apiToken' => 'your-token',
        'apiSecret' => 'your-secret',
        'judoId' => 'your-judo-id',
        //Set to true on production, defaults to false which is the sandbox
        'useProduction' => false
    )
);

For the purpose of this exercise, the sandbox token and secret have been added.

  1. Ensure the SDK is configured for the environment you are targeting.

    • For example, if you are using the sandbox environment: 'useProduction' => false

 

The Server SDK allows for further configuration:

  • Logging. To help debug you can attach a logger library.

    We recommend Monolog, however any PSR-3 standard library is compatible.

Validation error details can be found in the modelErrors array. For example if a required field is missing from the model.

 

Other Payment Methods using the Server SDKs:

To send payment requests with the wallet details from Apple Pay™ and Google Pay™, see our Transaction API for more information.

 

Check Card

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

 

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

Create an instance of the CheckCard Model:

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

 

 

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.

 

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.

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

 

 

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

 

Register Card

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

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

Create an instance of the RegisterCard Model

 

You do not need to set an amount. This is automatically set by Judopay's Transaction API in order to register the card.
The receipt response will show the payment: Type = PreAuth.

 

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.

 

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.

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

 

 

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

 

Save Card

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

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

 

Create an instance of the SaveCardModel:

 

 

Parameter

Description

 

cardNumber

String

Required

Submitted without whitespace or non-numeric characters.

 

expiryDate

String

Optional

The expiry date of the card.

Format: 

  • MM/YY

 

cardAddress

Object

Optional

Card holder address.

 

startDate

String

Optional

For Maestro cards:

Format: 

  • MM/YY

 

issueNumber

String

Optional

For Maestro cards:

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

  • Located on the front of the card.

 

yourConsumerReference

String

Required

Unique reference to anonymously identify your customer.

Advisable to use GUIDs.

Must be below 40 characters.

 

judoId

String

Required

Unique ID supplied by Judopay.

Specific to a merchant and/or location.

Format:

  • 100100100

  • Maximum length 9 characters.

  • Do not include spaces or dashes.

 

currency

String

Optional

The currency of the transaction. 

Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

 

cardHolderName

String

Required

The card name of the consumer.

 

 

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

 

Token Payments

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

 

Create an instance of the TokenPaymentModel:

 

 

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

This must match the original yourConsumerReference when the token was initially created.

 

yourPaymentReference

String

Required

Set your unique reference for this payment. 

Format:

  • Maximum length 50 characters.

  • This value should be unique in order to protect your customers against duplicate transactions. 

  • With a server side integration, if a payment reference is not supplied, the transaction will not be processed.

 

yourPaymentMetaData

IDictionary

Optional

Additional information associated with a transaction to help reconcile.

 

judoId

String

Required

Unique ID supplied by Judopay.

Specific to a merchant and/or location.

Format:

  • 100100100

  • Maximum length 9 characters.

  • Do not include spaces or dashes.

 

amount

Decimal

Required

The amount to process. 

Format:

  • Two decimal places

  • For currencies using a different structure please contact Judopay for support.

 

currency

String

Optional

The currency of the transaction. 

Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

 

userAgent

String

Optional

Consumer's browser details.

 

deviceCategory

String

Optional

The type of device where the consumer is carrying out the transaction:

  • Mobile

 

acceptHeaders

String

Optional

Consumer's browser details.

 

cardAddress

Object

Optional

Card holder's billing address.

Values:

  • address1

  • address2 (optional)

  • address3 (optional)

  • town

  • state (only required if country is USA/Canada)

  • country

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

 

 

Check the Payment Receipt Model response.

 

Creating a PreAuth

Create an instance of the CardPaymentModel:

 

 

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

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.

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.

 

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.

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

 

 

Check the Payment Receipt Model response.

 

Creating a Collection

Partial collections are supported. Use the same ReceiptId to collect different amounts up to the original preauth amount.
You cannot collect more than the original amount.

 

Following the preAuth, prepare the collection:

 

 

Parameter

Description

 

receiptId

String

Required

Judopay’s reference for the transaction. 

Required for you to process the collection.

 

Get the receiptId from the original preauth transaction response.

 

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.		 

amount

Float

Required

The amount to process. 

Format:

  • Two decimal places

For currencies using a different structure please contact Judopay for support.

 

 

Check the response: Payment Receipt Model.

 

Voiding a PreAuth Transaction

Cancel a pre-authorised transaction if the funds have not yet settled.

Voids cannot be performed on transactions that have been collected (partial or full).

 

Create a void request:

 

 

  • Parameter

  • Description

 

judoId

String

Required

Only applies to PHP integrations.

Unique ID supplied by Judopay.

Specific to a merchant and/or location.

Format:

  • 100100100

  • Maximum length 9 characters.

  • Do not include spaces or dashes.

 

receiptId

String

Required

The preAuth receiptId.

Required for you to process the void.

 

amount

Decimal

The amount field is required for PHP integrations.
Optional for .NET integrations.

The amount to process.

 Format:

  • Two decimal places

For currencies using a different structure please contact Judopay for support

 

 

If response.HasError = false, check the Payment Receipt Modelresponse.

 

Creating a Payment

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

 

Create an instance of the CardPaymentModel:

 

 

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

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.

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.

 

 

 

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

 

3D Secure 2 Transaction Flow

Authenticate a 3D Secure 2 transaction to allow for additional transaction checks required for compliance with Strong Customer Authentication (SCA).

For more information on 3D Secure 2 and SCA, see What is Strong Customer Authentication?

Make sure your account has 3D Secure 2 enabled. Contact ​Customer Support​​ to set this up.

 

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

 

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.

  • SecureCorporate

    • Request exemption for payments made using a corporate card.

  • TrustedBeneficiary

    • Provides the 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.

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

 

 

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

 

 

Parameter

Description

 

cv2

String

Required

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

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

methodCompletion

enum

Required

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

Values:

  • Unknown

  • Yes

  • No

  • Unavailable

 

primaryAccountDetails

Object

For MCC 6012 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

 

 

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

For MCC 6012 merchants, this object needs to be added to the request.
Without this, 3D Secure 2 transactions will not be successful.

Values:

  • name

  • accountNumber

  • dateOfBirth

  • postCode

 

 

Check the Payment Receipt Model response.

 

Payment Receipt Model

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

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

  • 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

 

challengeRequestIndicator

String

Optional

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

Optional

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

Optional

Type of recurring payment.

Values:

  • RECURRING

    • Scheduled regular payment.

  • MIT (Merchant Initiated Transaction)

    • Unscheduled regular payment.

recurringPaymentType is required if recurringPayment = true.

 

 

Creating a Refund

You can process a full or partial refund.

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

 

Create a refund request:

 

 

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

 

 

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

 

Going Live

Test all your required transaction types in the live environment before deploying your app.

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

 

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

 

  • 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 Portal >  History

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