.NET

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.

 

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.

  1. Create an instance of the CheckCard Model:

 var checkCardRequest = new CheckCardModel
   {
     CV2 = "452",
     CardNumber = "4976000000003436",
     ExpiryDate = "12/25",
     JudoId = "yourJudoId", 
     YourConsumerReference =  "yourUniqueReference",
   };

 

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

 

 

  1. Send the request to Judopay:

var result = await 
client.CheckCards.Create(checkCardRequest)
  1. If result.HasError = false, check the paymentReceipt 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

  1. Create an instance of the RegisterCard Model:

var register = new RegisterCardModel {         
    JudoId = "yourJudoId",         
    YourConsumerReference = "yourUniqueReference",         
    YourPaymentReference = "yourPaymentReference",         
    CardNumber = "4906000780007612",         
    ExpiryDate = "12/25",        
    CV2 = "452",         
        CardAddress = new CardAddressModel {             
            PostCode = "postCode"        
                    }         
        ThreeDSecure = new ThreeDSecureTwoModel {         
              AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser,           
            ChallengeRequestIndicator = ThreeDSecureTwoChallengeRequestIndicator.ChallengePreferred,
            ScaExemption = ThreeDSecureTwoScaExemption.SecureCorporate   
        }
};

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

 

 

  1. Send the register request to Judopay:

var result = await 
client.RegisterCards.Create(register);
if (!result.HasError)

{
    var receipt = result.Response as PaymentReceiptModel;
}

 

  1. If result.HasError = false, check the paymentReceipt 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.

  1. Create an instance of the SaveCardModel:

var saveCardRequest = new SaveCardModel()
   {
      CardNumber = "4976000000003436",
      ExpiryDate = "12/25",
      JudoId = cybersourceJudoId,
      YourConsumerReference = "ASC123",
 };

 

 

  1. Send the request to Judopay:

var result = await
client.SaveCards.Create(saveCardRequest);

 

  1. If result.HasError = false, check the paymentReceipt 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

  1. Create an instance of the TokenPaymentModel:

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

 

 

  1. Send the request to Judopay using the token received from the RegisterCard response: var Receipt = await client.Payments.Create(tokenPayment);

  1. Check the paymentReceipt Model response.

 

Creating a PreAuth

  1. Create an instance of the CardPaymentModel:

Copy
var preauth = new CardPaymentModel
 {
   JudoId = "yourJudoId",
   YourConsumerReference = "yourUniqueReference",
   YourPaymentReference = "yourPaymentReference",
   Amount = 25,
   CardNumber = "4906000780007612",
   CV2 = "452",
   ExpiryDate = "12/25",
   CardAddress = new CardAddressModel
      {
        PostCode = "postCode"
           }
   ThreeDSecure = new ThreeDSecureTwoModel
       {
         AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser,
         ChallengeRequestIndicator = ThreeDSecureTwoChallengeRequestIndicator.ChallengePreferred,
         ScaExemption = ThreeDSecureTwoScaExemption.SecureCorporate
               }
};            

 

 

  1. Send the preauth to Judopay: var preauthResult = await client.PreAuths.Create(preauth);

  2. If the preauthResult.response = successful collect the preauth amount:

Copy
if (!result.HasError)  {   
var collection = new CollectionModel()    {      
ReceiptId = result.Response.ReceiptId,      
Amount = 20      };                
var collectionResponse = await client.Collections.Create(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.

  1. Check the paymentReceipt Model response.

 

Creating a Payment

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

  1. Create an instance of the CardPaymentModel:

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

 

 

  1. Send the payment to Judopay: var response = await client.Payments.Create(payment);

  2. If response.HasError = true, check the error content:

{Code = 403Message = 
"Sorry, but we were unable to authenticate your request. Please check your details and try again.
"Category = 1}
  1. If response.HasError = false, check the paymentReceipt 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?

 

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

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

 

 

  1. Send the 3D Secure 2 transaction request to Judopay: var result = await client.Payments.Create(paymentModel);

  1. Check the response.

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.

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

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

 

 

  1. Resume the transaction flow to Judopay: var resumeResult = await client.ThreeDs.Resume3DSecureTwo(result.Response.ReceiptId, resumeModel);

Use the ReceiptId from the original response

 

  1. Check the response.

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

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

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

 

 

  1. Complete the transaction flow to Judopay: var completeResult = await client.ThreeDs.Complete3DSecureTwo(result.Response.ReceiptId, completeModel);

  1. Check the paymentReceipt Model response.

 

 

 

Creating a Refund

You can process a full or partial refund.

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

  1. Create a refund request:

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

 

 

  1. Send the refund request to Judopay: result = await client.Refunds.Create(refund);

  1. If response.HasError = false, check the paymentReceipt Model response.

 

Going Live with .Net

Use the live environment for testing 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

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

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

  • Replace your sandbox API Token and Secret for the live API Token and Secret 

    • Find these in Judopay Portal > Your apps > {app name} > Live Tokens

 

3. Test Live Payments

  • Ensure the SDK is properly configured for the live  environment

  • Use real debit or credit cards

    • Test cards provided will not work in live

    • We recommend to perform pre-authorizations followed by a void, or regular payments followed by a refund 

    • Send a refund through the  Judopay PortalHistory

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

 

PHP

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": "4.4.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.

 

Check Card

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

  1. Prepare the check card request:

   $checkCard = $judopay->getModel('CheckCard');    $attributes = [
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'judoId' => '100915867',
        'yourConsumerReference' => 'consumerRef',
        'yourPaymentReference' => 'paymentRef' 
    ];    $checkCard->setAttributeValues($attributes);

 

 

  1. Send the request:

try {
    $response = $checkCard->create();
    // Handle successful payment    
     $cardToken = $response['cardDetails']['cardToken'];
     } catch (\Exception $e) {
    // Handle the errors
    return;
}

 

  1. Get the card token from the response:

    $cardToken = $response['cardDetails']['cardToken'];

     

 

Build the token payment using the card token from the response.

 

If you see the following error message: "Sorry, we're currently unable to route this transaction. Please check your account details and try again"
Your Judopay account is not configured for the check card operation. Contact Customer Support.

 

Register Card

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

  1. Prepare the register card request:

$registerCard = $judopay->getModel('RegisterCard');    
     $attributes = [
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'judoId' => '100915867',
        'yourConsumerReference' => 'consumerRef',
        'yourPaymentReference' => 'paymentRef'
    ];    $registerCard->setAttributeValues($attributes);

 

 

  1. Send the request to Judopay:

 try {
        $response = $registerCard->create();
             // Handle successful payment        
             $cardToken = $response['cardDetails']['cardToken'];    
                 } catch (\Exception $e) {
                 // Handle the errors
               return;
    }

 

  1. Get the card token from the response:

    $cardToken = $response['cardDetails']['cardToken'];

 

Build the token payment using the card token from the response.

 

Token Payments

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

  1. Prepare the token payment:

$tokenPayment = $judopay->getModel('TokenPayment');   
 $tokenPaymentAttributes = [
        'amount' => 1.10,
        'cardToken' => $cardToken,
        'expiryDate' => '12/25',
        'yourConsumerReference' =>  'consumerRef',
        'yourPaymentReference' => 'paymentRef',
        'cv2' => '452',
        'currency' => 'GBP',
        'judoId' => '100915867'
    ];    $tokenPayment->setAttributeValues($tokenPaymentAttributes);

 

 

  1. Send the token payment:

try {
        $tokenPaymentResponse = $tokenPayment->create();
        // Handle successful payment    
        } catch (\Exception $e) {
        // Handle the errors
        return;
    }

 

  1. Check the result.

    See paymentReceipt Model.

 

Creating a PreAuth

  1. Prepare the preauth:

$preauth = $judopay->getModel('Preauth');    
        $attributes = [
        'amount' => 1.10,
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'yourConsumerReference' => 'azerty',
        'yourPaymentReference' => 'azerty',
        'cv2' => '452',
        'currency' => 'GBP',
        'judoId' => '100915867'
    ];  $preauth->setAttributeValues($attributes);

 

 

  1. Send the preauth:

try {
        $response = $preauth->create();
        // Handle successful payment
        return;
    } catch (\Exception $e) {
       echo $e->getMessage();
        // Handle the errors
        return;
    }

 

  1. Check the result: paymentReceipt Model

    If the preauth response = successful, collect the preauth amount. See, 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.

 

Creating a Collection

  1. Prepare the collection:

 $collection = $judopay->getModel('Collection');   
        $collectionAttributes = [
        'amount' => 1.10,
        'receiptId' => $receiptId,
        'yourPaymentReference' => 'qsdfg'
    ];    $collection->setAttributeValues($collectionAttributes);

 

 

  1. Send the collection:

try {
    $response = $collection->create();
    // Handle successful collection} 
        return;
            } catch (\Exception $e) {
            echo $e->getMessage();
        // Handle the errors 
       return;
    }

 

  1. Check the response: paymentReceipt Model.

 

Creating a Payment

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

  1. Prepare the payment:

 $payment = $judopay->getModel('Payment');    
   $attributes = [
        'amount' => 1.10,
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'yourConsumerReference' => 'consumerRef',
        'yourPaymentReference' => 'paymentRef',
        'cv2' => '452',
        'currency' => 'GBP',
        'judoId' => '100200300'
    ];   $payment->setAttributeValues($attributes);    

 

 

  1. Send the payment:

 try {
        $response = $payment->create();
        // Handle successful payment
        return;
            } catch (\Exception $e) {
            echo $e->getMessage();
        // Handle the errors 
        return;
    }

 

  1. Check the result.

For the purpose of this exercise, the payment is successful:
Array
    (
        [receiptId] => 520882
        [type] => Payment
        [createdAt] => 2014-08-18T16:28:39.6164+01:00
        [result] => Success
        ...
        [amount] => 1.10
        ...    
        [yourPaymentReference] => 12345
    )

 

See, paymentReceipt Model.

 

3D Secure 2 Transaction Flow

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

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

 

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

 $payment = $judopay->getModel('Payment');    
   $attributes = [     
    ...
        'cardHolderName' => 'First Last',
        'mobileNumber' => '07999999999',
        'phoneCountryCode' => '41',
        'emailAddress' => 'contact@judopay.com',
        'threeDSecure' => [
            'authenticationSource' => 'BROWSER',
            'methodCompletion' => 'no'
        ]
    ];   

 

 

  1. Send the 3D Secure 2 payment:

 try
    {
        $cardPayment->setAttributeValues($attributes);
        $response = $cardPayment->create();
    } catch (\Exception $e) {
        return;
    }

 

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.

  1. Check the response. For the purpose of this exercise the challenge response has been returned, requesting: "Additional device data is needed for 3D Secure 2".

  1. Once the additional device data has been collected, resume the transaction flow to Judopay:

Copy
ResumeThreeDSecureTwo:
 $resumeRequest = $judopay3ds2->getModel('ResumeThreeDSecureTwo');
        $attributes = [
            'receiptId' => $response['receiptId'],
            'cv2' => '452',
            'methodCompletion' => 'no'
        ];
        $resumeRequest->setAttributeValues($attributes);       
 $response = $resumeRequest->update();

 

Use the ReceiptId from the original response.

  1. Check the response.

    For the purpose of this exercise, the completion response has been returned, requesting: "Challenge completion is needed for 3D Secure 2":

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

  1. Complete the transaction flow to Judopay.

Copy
CompleteThreeDSecureTwo:
   $completeRequest = $judopay3ds2->getModel('CompleteThreeDSecureTwo');
        $attributes = [
            'receiptId' => $response['receiptId'],
            'cv2' => '452'
        ];
        $completeRequest->setAttributeValues($attributes);       
 $response = $completeRequest->update();

 

  1. Check the response: paymentReceipt Model.

 

 

Creating a Refund

  1. Prepare the refund:

$refund = $judopay->getModel('Refund');    
        $refundAttributes = [
        'amount' => 1.10,
        'receiptId' => $receiptId,
        'yourPaymentReference' => 'qsdfg'
    ];    $refund->setAttributeValues($refundAttributes);

 

 

  1. Send the refund:

 try {
        $response = $refund->create();
        // Handle successful refund   
          return;
            } catch (\Exception $e) {
            echo $e->getMessage();
        // Handle the errors 
        return;
    }

 

  1. Check the response: paymentReceipt Model

 

Going Live with PHP

Test all your required transaction types in the live environment.

You will need to have tested your app in the sandbox environment before going live.
Use the test cards provided in the Judopay Portal: Tools  > Generating transactions.

 

1. Activate your Account

  • To process live payments, ensure you have a live account.

  • Complete the activation form for us to make the necessary changes to your account. 

We will contact you as soon as you are live.

 

2. Point to the Live Environment

  • In the Judopay object , change the production environment setting from false to true: 'useProduction' => true

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

$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' => true    )
);