.NET and PHP Integrations

.NET and PHP SDKs
Integration
.NET
PHP
From Visual Studio launch: NuGet Package Manager
Search for JudoPay.Net 
Add JudoPay.Net via
GUI, or
Package Manager Console 
Add the JudoPay.Net package:
install-Package JudoPay.Net
For examples on integrating with the .NET Server SDK, see our sample app for more information.
 
Prerequisites
PHP 5.5 and above
Composer Package Manager
Integration
Using the Composer Package Manager:
Add the Judopay package to your composer.json file:
"require": {"judopay/judopay-sdk": "5.1.0"}
Execute:
$ composer install
Make the Judopay SDK classes available to your application, by adding the following to your file:
require 'vendor/autoload.php';
For examples on Integrating PHP with the Server SDK, see our sample app for more information.
 
﻿
Only sandbox API tokens and secrets will work in the sandbox.
Using the wrong tokens and secrets will result in an authorisation failure.
Setup
.NET
PHP
Ensure all integration steps are completed.
Add your app’s sandbox Token and Secret:
var client = JudoPaymentsFactory.Create(
 JudoEnvironment.Sandbox,
 <yourApiToken>, 
<yourApiSecret> 
);
Ensure the SDK is configured for the sandbox environment.
Use the test cards provided in the Judopay Portal:
Tools > Generating transactions
Create a separate app for your backend with the Make Payments permission enabled.
Test all your required payment types in the sandbox environment before going live.
For our DotNetSDK core sample app, see DotNetSDK.
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
 )
);
Ensure the SDK is configured for the environment you are targeting.
For example, if you are using the sandbox environment: 'useProduction' => false.
For the purpose of this exercise, the sandbox token and secret have been added.
﻿
The Server SDK allows for further configuration:

Logging
To help debug you can attach a logger library.
Validation error details can be found in the modelErrors array. 
For example if a required field is missing from the model.
Other Payment Methods using the Server SDKs
To send payment requests with the wallet details from Apple Pay™ and Google Pay™, see our Transaction API﻿ for more information.
﻿
Check Card
Ensure your account supports the Check Card functionality. 
Contact Developer Support for more details.
When making Token Payments﻿, you can obtain the card token from the Check Card response.
Create an instance of the CheckCard Model:
.NET
PHP
//Create an instance of the CheckCard Model
var checkCardRequest = new CheckCardModel
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    YourPaymentReference = "yourPaymentReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25",
    CV2 = "452",
    CardAddress = new CardAddressModel
    {
        Address1 = "41 Luke St",
        PostCode = "EC2A 4DP",
        Town = "London",
        CountryCode = 826
    },
    // PrimaryAccountDetails only required for MCC6012 merchants
    PrimaryAccountDetails = new PrimaryAccountDetailsModel
    {
        Name = "Smith",
        AccountNumber = "1234567",
        DateOfBirth = "2000-12-31",
        PostCode = "EC2A 4DP"
    },
    // Following are for 3DS2 transactions
    PhoneCountryCode = "44",
    MobileNumber = "7999123456",
    EmailAddress = "[email protected]",
    CardHolderName = "John Smith",
    ThreeDSecure = new ThreeDSecureTwoModel
    {
        AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser,
        ChallengeRequestIndicator = ThreeDSecureTwoChallengeRequestIndicator.ChallengeAsMandate,
        MethodNotificationUrl = "https://yourMethodNotificationUrl",
        ChallengeNotificationUrl = "https://yourChallengeNotificationUrl"
    }
};

//Send the request to Judopay
var response = await client.CheckCards.Create(checkCardRequest);

if (response.HasError)
{
    if (response.Error.Code == (int)HttpStatusCode.Forbidden)
    {
        // Failed to authenticate - check your credentials
    }
    else if (response.Error.ModelErrors != null)
    {
        // Validation failed on the request, check each list entry for details
    }
    else
    {
        // Refer to https://docs.judopay.com/Content/Developer%20Tools/Codes.htm#Errors
        var errorCode = response.Error.Code;
    }
}
else if (response.Response is PaymentRequiresThreeDSecureTwoModel threeDSecureTwoResponseModel)
{
    if (threeDSecureTwoResponseModel.MethodUrl != null)
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        var methodUrl = threeDSecureTwoResponseModel.MethodUrl;
        var md = threeDSecureTwoResponseModel.Md;
    }
    else if (threeDSecureTwoResponseModel.ChallengeUrl != null)
    {
        // Challenge is required - POST creq to challengeUrl
        var challengeUrl = threeDSecureTwoResponseModel.ChallengeUrl;
        var creq = threeDSecureTwoResponseModel.CReq;
    }
}
else if (response.Response is PaymentReceiptModel receipt)
{
    var receiptId = receipt.ReceiptId;
    var status = receipt.Result;
    if (receipt.Result == "Success")
    {
        var cardToken = receipt.CardDetails.CardToken;
    }
}
//Create an instance of the CheckCard Model
var checkCardRequest = new CheckCardModel
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    YourPaymentReference = "yourPaymentReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25",
    CV2 = "452",
    CardAddress = new CardAddressModel
    {
        Address1 = "41 Luke St",
        PostCode = "EC2A 4DP",
        Town = "London",
        CountryCode = 826
    },
    // PrimaryAccountDetails only required for MCC6012 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;
    }
}
﻿
You do not need to set an amount. 
This is automatically set by Judopay's Transaction API in order to check the card.
﻿
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:
.NET
PHP
//Prepare the RegisterCard request
$registerCardRequest = $judopay->getModel('RegisterCard');

$registerCardRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => '[email protected]',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $registerCardRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}

//Prepare the RegisterCard request
$registerCardRequest = $judopay->getModel('RegisterCard');

$registerCardRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            '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' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $registerCardRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
﻿
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:
.NET
PHP
//Create an instance of the SaveCardModel
var saveCardRequest = new SaveCardModel()
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25"
};
 
//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;
    }
}
//Create an instance of the SaveCardModel
var saveCardRequest = new SaveCardModel()
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25"
};
 
//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;
    }
}
﻿
﻿
If result.HasError = false, check the Payment Receipt Model﻿ response. 
﻿
Token Payments
You can create a token payment following a: Payment | PreAuth | Save Card operation, as a card token is always returned.
Create an instance of the TokenPaymentModel:
.NET
PHP
//Prepare the TokenPayment request
$tokenPaymentRequest = $judopay->getModel('TokenPayment');

$tokenPaymentRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardToken' => 'cardTokenFromPreviousTransaction',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 customer-initiated transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => '[email protected]',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        ),
        // Following are for merchant-initiated transactions
        'recurringPayment' => true,
        'recurringPaymentType' => 'mit', // Unscheduled, use recurring for scheduled payments
        'relatedReceiptId' => 'receiptIdOfOriginalCustomerInitiatedTransaction'
    )
);

try {
    //Send the request to Judopay
    $response = $tokenPaymentRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
//Prepare the TokenPayment request
$tokenPaymentRequest = $judopay->getModel('TokenPayment');

$tokenPaymentRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardToken' => 'cardTokenFromPreviousTransaction',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            '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' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        ),
        // Following are for merchant-initiated transactions
        'recurringPayment' => true,
        'recurringPaymentType' => 'mit', // Unscheduled, use recurring for scheduled payments
        'relatedReceiptId' => 'receiptIdOfOriginalCustomerInitiatedTransaction'
    )
);

try {
    //Send the request to Judopay
    $response = $tokenPaymentRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
﻿
﻿
If result.HasError = false, check the Payment Receipt Model﻿ response. 
﻿
Creating a PreAuth
Create an instance of the CardPayment Model:
.NET
PHP
//Create an instance of the CardPayment Model
var preauthRequest = new CardPaymentModel
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    YourPaymentReference = "yourPaymentReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25",
    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 merchants
    PrimaryAccountDetails = new PrimaryAccountDetailsModel
    {
        Name = "Smith",
        AccountNumber = "1234567",
        DateOfBirth = "2000-12-31",
        PostCode = "EC2A 4DP"
    },
    // Following are for 3DS2 transactions
    PhoneCountryCode = "44",
    MobileNumber = "7999123456",
    EmailAddress = "[email protected]",
    CardHolderName = "John Smith",
    ThreeDSecure = new ThreeDSecureTwoModel
    {
        AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser,
        ChallengeRequestIndicator = ThreeDSecureTwoChallengeRequestIndicator.ChallengeAsMandate,
        MethodNotificationUrl = "https://yourMethodNotificationUrl",
        ChallengeNotificationUrl = "https://yourChallengeNotificationUrl"
    }
};

//Send the request to Judopay
var response = await client.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;
    }
}
//Create an instance of the CardPayment Model
var preauthRequest = new CardPaymentModel
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    YourPaymentReference = "yourPaymentReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25",
    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 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.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;
    }
}
﻿
﻿
If result.HasError = false, check the Payment Receipt Model﻿ response. 
﻿
Creating a Collection
Partial collections are supported. 
Use the same ReceiptId to collect different amounts up to the original preauth amount.
You cannot collect more than the original amount.
Following the preAuth﻿, prepare the collection:
.NET
PHP
//Prepare the Collection request
$collectionRequest = $judopay->getModel('Collection');

$collectionRequest->setAttributeValues(
    array(
        'receiptId' => 'yourPreauthReceiptId',
        'yourPaymentReference' => 'yourCollectionReference',
        'amount' => 1.01
    )
);

try {
    //Send the request to Judopay
    $response = $collectionRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
//Prepare the Collection request
$collectionRequest = $judopay->getModel('Collection');

$collectionRequest->setAttributeValues(
    array(
        'receiptId' => 'yourPreauthReceiptId',
        'yourPaymentReference' => 'yourCollectionReference',
        'amount' => 1.01
    )
);

try {
    //Send the request to Judopay
    $response = $collectionRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
﻿
﻿
Check the Payment Receipt Model﻿ response. 
﻿
Voiding a PreAuth Transaction
Cancel a pre-authorised transaction if the funds have not yet settled.
Voids cannot be performed on transactions that have been collected (partial or full).
Create a void request:
.NET
PHP
//Prepare the Void request
$voidRequest = $judopay->getModel('VoidTransaction');

$voidRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId', // This attribute will not be required in the next version of the SDK
        'receiptId' => 'yourPreauthReceiptId',
        'yourPaymentReference' => 'yourVoidReference',
        'amount' => 1.01
    )
);

try {
    //Send the request to Judopay
    $response = $voidRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
//Prepare the Void request
$voidRequest = $judopay->getModel('VoidTransaction');

$voidRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId', // This attribute will not be required in the next version of the SDK
        'receiptId' => 'yourPreauthReceiptId',
        'yourPaymentReference' => 'yourVoidReference',
        'amount' => 1.01
    )
);

try {
    //Send the request to Judopay
    $response = $voidRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
﻿
﻿
If result.HasError = false, check the Payment Receipt Model﻿ response. 
﻿
Creating a Payment
When handling exceptions, it is good practice to use Try Catch Block.
Create an instance of the CardPayment Model:
.NET
PHP
//Prepare the Payment request
$paymentRequest = $judopay->getModel('Payment');

$paymentRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => '[email protected]',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $paymentRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
//Prepare the Payment request
$paymentRequest = $judopay->getModel('Payment');

$paymentRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            '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' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $paymentRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
﻿
﻿
If result.HasError = false, check the Payment Receipt Model﻿ response. 
﻿
3D Secure 2 Transaction Flow
Authenticate a 3D Secure 2 transaction to allow for additional transaction checks required for compliance with Strong Customer Authentication (SCA). 
For more information on 3D Secure 2 and SCA, see What is Strong Customer Authentication﻿?
﻿
The instance of the CardPaymentModel you created for Creating a Payment﻿, just needs the following additional 3D Secure 2 parameters to be included:
.NET
PHP
// 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, resume the transaction flow to Judopay
$resumeRequest = $judopay->getModel('ResumeThreeDSecureTwo');
$resumeRequest->setAttributeValues(
    array(
        'receiptId' => $response['receiptId'], // receiptId of the original transaction
        'methodCompletion' => 'yes',
        'cv2' => '452',
        // primaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        )
    )
);

try {
    //Send the request to Judopay
    $resumeResponse = $resumeRequest->update();

    if ($resumeResponse['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $resumeResponse['challengeUrl'];
        $creq = $resumeResponse['creq'];
    }
    else
    {
        // Transaction has been processed
        $receiptId = $response['receiptId'];
        $status = $response['result'];
    }
}
catch (\Judopay\Exception\ApiException $resumeApiException)
{
    $resumeErrorResponse = "{\"error\":\"{$resumeApiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $resumeValidationErrors)
{
    // Required attributes are missing from the request
    $resumeErrorResponse = "{\"error\":\"{$resumeValidationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $resumeException)
{
    $resumeErrorResponse = "{\"error\":\"".$resumeException->getMessage()."\",\"result\":\"Error\"}";
}


// 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, complete the transaction flow to Judopay

$completeRequest = $judopay>getModel('CompleteThreeDSecureTwo');
$completeRequest->setAttributeValues(
    array(
        'receiptId' => $response['receiptId'], // receiptId of the original transaction
        'cv2' => '452',
        // primaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        )
    )
);

try {
    //Send the request to Judopay
    $completeResponse = $completeRequest->update();

    // Transaction has been processed
    $receiptId = $completeResponse['receiptId'];
    $status = $completeResponse['result'];
}
catch (\Judopay\Exception\ApiException $completeApiException)
{
    $completeErrorResponse = "{\"error\":\"{$completeApiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $completeValidationErrors)
{
    // Required attributes are missing from the request
    $completeErrorResponse = "{\"error\":\"{$completeValidationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $completeException)
{
    $completeErrorResponse = "{\"error\":\"".$completeException->getMessage()."\",\"result\":\"Error\"}";
}
// 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, resume the transaction flow to Judopay
$resumeRequest = $judopay->getModel('ResumeThreeDSecureTwo');
$resumeRequest->setAttributeValues(
    array(
        'receiptId' => $response['receiptId'], // receiptId of the original transaction
        'methodCompletion' => 'yes',
        'cv2' => '452',
        // primaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        )
    )
);

try {
    //Send the request to Judopay
    $resumeResponse = $resumeRequest->update();

    if ($resumeResponse['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $resumeResponse['challengeUrl'];
        $creq = $resumeResponse['creq'];
    }
    else
    {
        // Transaction has been processed
        $receiptId = $response['receiptId'];
        $status = $response['result'];
    }
}
catch (\Judopay\Exception\ApiException $resumeApiException)
{
    $resumeErrorResponse = "{\"error\":\"{$resumeApiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $resumeValidationErrors)
{
    // Required attributes are missing from the request
    $resumeErrorResponse = "{\"error\":\"{$resumeValidationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $resumeException)
{
    $resumeErrorResponse = "{\"error\":\"".$resumeException->getMessage()."\",\"result\":\"Error\"}";
}


// 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, complete the transaction flow to Judopay

$completeRequest = $judopay>getModel('CompleteThreeDSecureTwo');
$completeRequest->setAttributeValues(
    array(
        'receiptId' => $response['receiptId'], // receiptId of the original transaction
        'cv2' => '452',
        // primaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        )
    )
);

try {
    //Send the request to Judopay
    $completeResponse = $completeRequest->update();

    // Transaction has been processed
    $receiptId = $completeResponse['receiptId'];
    $status = $completeResponse['result'];
}
catch (\Judopay\Exception\ApiException $completeApiException)
{
    $completeErrorResponse = "{\"error\":\"{$completeApiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $completeValidationErrors)
{
    // Required attributes are missing from the request
    $completeErrorResponse = "{\"error\":\"{$completeValidationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $completeException)
{
    $completeErrorResponse = "{\"error\":\"".$completeException->getMessage()."\",\"result\":\"Error\"}";
}
﻿
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 cardholder the option to add the merchant to their trusted list.
TransactionRiskAnalysis
Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.

Make sure when testing:
methodNotificationUrl
and 
challengeNotificationUrl
you use a real URL for the values. 
If you use a localhost URL, it will not work.
methodNotificationUrl The URL that will receive the method completion message, confirming the Issuer has completed the device details check.
URL
Length: 1-256 characters
challengeNotificationUrl The URL that will receive the outcome of the challenge request to the consumer.
URL
Length: 1-256 characters
﻿
If no additional transaction checks are required, you will receive the usual paymentReceipt response.
If additional transaction checks are required, you will receive the challenge response.
Parameter
Description
cv2
String
Required﻿
The 3 or 4 digit number on the back of a credit card.
Also known as the card verification value (CVV) or security code.
primaryAccountDetails
Object
Optional﻿
For MCC 6012 merchants, this object needs to be added to the request. Without this, 3D Secure 2 transactions will not be successful.
 Values:
name
accountNumber
dateOfBirth
postCode
methodCompletion
enum
Required﻿
Indicates if the 3DS ACS method to collect the device details was completed successfully.
Values:
Unknown
Yes
No
Unavailable
﻿
Parameter
Description
cv2
String
Required﻿
﻿
The 3 or 4 digit number on the back of a credit card.
Also known as the card verification value (CVV) or security code.
primaryAccountDetails
Object
Optional﻿
﻿
For MCC 6012 merchants, this object needs to be added to the request. Without this, 3D Secure 2 transactions will not be successful.
 Values:
name
accountNumber
dateOfBirth
postCode
﻿
Check the Payment Receipt Model﻿ response. 
﻿
Payment Receipt
Parameter
Description
receiptId
String
Judopay's reference for the transaction.
Used to process refunds or collections.
yourPaymentReference
String
Your unique reference for this payment. 
This value should be unique in order to protect your customers against duplicate transactions. 
With a server side integration, if a payment reference is not supplied, the transaction will not be processed.
type
String
Type of transaction:
Payment
Refund
PreAuth
Collection
This transaction type is available from API Version 6.4.1 onwards.
acquirerTransactionID
String
The unique ID of a transaction set by the acquirer.
createdAt
Date
An ISO8601 formatted date and time.
Includes time zone offset.
result
String
Result of transaction.
message
String
Message detailing the outcome.
externalBankResponseCode
String
Reason code provided by the bank for declined transactions.
judoId
String
Unique ID supplied by Judopay. 
Specific to a merchant and/or location.
merchantName
String
Merchant's trading name.
appearsOnStatementAs
String
How the Merchant appears on the consumer's statement.
originalAmount
Decimal
Amount of transaction.
This field will not be included for Refund and PreAuth transaction types.
amountCollected
Decimal
Amount collected.
This field will be included for the PreAuth transaction type.
netAmount
Decimal
The remaining balance of the transaction after a refund.
You cannot refund more than the original transaction amount.
amount
Decimal
The amount to process. 
Format:
Two decimal places
For currencies using a different structure please contact Judopay for support.
currency
String
The currency of the transaction.
Any ISO 4217 alphabetic currency code:
GBP
USD
EUR
cardDetails
Object
Information on the card used in this transaction:
cardLastFour
endDate
cardToken
cardType
startDate
cardScheme
cardFunding
cardCategory
cardCountry
bank
consumer
Object
Details of the consumer.
Used for repeat transactions.
Details:
yourConsumerReference
device
Object
Specific device details to identify a consumer:
identifier
riskScore
Integer
Consumer's risk score.
yourPaymentMetaData
String
Additional information associated with a transaction to help reconcile.
threeDSecure
Object
For any 3DSecure requests.
Includes the result of the authentication process:
attempted
result
This block will not be returned for voids / refunds or collections responses.
challengeRequestIndicator
String
Indicates the type of challenge request you wish to apply.
Values:
noPreference
noChallenge
No challenge required.
challengePreferred
A challenge is preferred for this transaction.
challengeAsMandate
Must challenge this transaction.
scaExemption
String
To apply for an exemption from SCA, for a customer initiated transaction.
Values:
lowValue
Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
secureCorporate
Request exemption for payments made using a corporate card.
trustedBeneficiary
Provides the cardholder the option to add the merchant to their trusted list.
transactionRiskAnalysis
Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.
risks
Object
Risk checks on:
postCodeCheck
cv2Check
merchantSuggestion
merchantStatistics
recurring
Boolean
Is the transaction a recurring transaction?
If false, the field will not be returned.
recurringPaymentType
enum
﻿
﻿
﻿
﻿
Type of recurring payment.
Values:
RECURRING
Scheduled regular payment.
MIT (Merchant Initiated Transaction)
Unscheduled regular payment.
recurringPaymentType is required if recurringPayment = true.
﻿
﻿
Creating a Refund
You can process a full or partial refund.
Ensure the Refund Payments permission is enabled on your API token.
Create a refund request:
.NET
PHP
//Prepare the Refund request
$refundRequest = $judopay->getModel('Refund');

$refundRequest->setAttributeValues(
    array(
        'receiptId' => 'yourPaymentReceiptId',
        'yourPaymentReference' => 'yourRefundReference',
        'amount' => 1.01 // Optional, if not specified full payment amount will be refunded
    )
);

try {
    //Send the request to Judopay
    $response = $refundRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
//Prepare the Refund request
$refundRequest = $judopay->getModel('Refund');

$refundRequest->setAttributeValues(
    array(
        'receiptId' => 'yourPaymentReceiptId',
        'yourPaymentReference' => 'yourRefundReference',
        'amount' => 1.01 // Optional, if not specified full payment amount will be refunded
    )
);

try {
    //Send the request to Judopay
    $response = $refundRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
﻿
﻿
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
.NET
PHP
//In the:
JudoPaymentsFactory.Create

//method, change the environment from Sandbox to Live:
var client = JudoPaymentsFactory.Create(JudoEnvironment.Live, "YOUR_API_TOKEN", "YOUR_API_SECRET");

//In the:
JudoPaymentsFactory.Create

//method, change the environment from Sandbox to Live:
var client = JudoPaymentsFactory.Create(JudoEnvironment.Live, "YOUR_API_TOKEN", "YOUR_API_SECRET");
﻿
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.
﻿

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.

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

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 merchants, this object needs to be added to the request. Without this, 3D Secure 2 transactions will not be successful. Values: name accountNumber dateOfBirth postCode
methodCompletion enum Required	Indicates if the 3DS ACS method to collect the device details was completed successfully. Values: Unknown Yes No Unavailable

Parameter	Description
cv2 String Required	The 3 or 4 digit number on the back of a credit card. Also known as the card verification value (CVV) or security code.
primaryAccountDetails Object Optional	For MCC 6012 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
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.

Updated 06 Aug 2024

Server SDK Integration

Apple Pay and Google Pay Wallets

.NET and PHP Integrations

.NET and PHP SDKs

Integration

Setup

Check Card

Register Card

Save Card

Token Payments

Creating a PreAuth

Creating a Collection

Voiding a PreAuth Transaction

Creating a Payment

3D Secure 2 Transaction Flow

Additional 3D Secure 2 Parameters

ResumeThreeDSecureTwo Model Parameters

CompleteThreeDSecureTwo Model Parameters

Payment Receipt

Payment Receipt Model Parameters

Creating a Refund

Going Live