Judopay Documentation

Integrate and Perform a Test Payment

The following example takes you through the steps to produce a card payment using Judopay’s Web SDK.

Note

The sample code uses PHP to directly call our API, however this can also be used as a guide in understanding how to call our API's by other methods.

Step 1: Customise and Create the iframe to Present a Pay Button

To customise and create the Judopay WebSDK iframe:

  1. Add the code snippet in your web page <HEAD>:

    https://web.judopay.com/js/0.0.11/judopay.min.js"></script>

    1. This example will use jQuery for a promise, so include the following in your web page <HEAD> :

      <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

  2. In your <BODY> add a <DIV> tag where you want the iframe to appear.

    <div id="payment-iframe" width="100%"></div>

Note

This example uses the id: payment-frame. You can use whatever id you wish.

  1. In your <BODY> add a <DIV> tag where you want the errors in form entry to appear.

    1. For the purpose of this exercise, the class is named judopay-errors, and sets a style to be red.

      You can add any custom style you wish in your .CSS file.

      <div class="judopay-errors" style="color:red">Error Location</div>

  2. In your <BODY> add a button call: submit-payment-button for the iframe submission to Judopay.

    1. Set this to disabled. The iframe will enable it when the input is valid. 

      You can apply any CSS styling you wish to this button.

    2. <button id="submit-payment-button" name="submit-payment" disabled> Pay Now </button>

  3. In your <BODY> add the following script for a minimum iframe. 

    1. This example names this style configMinimum which is used when calling the iframe:

<script>var configMinimum = {
iframe: {
language: "en",
    	errorFieldId: 'judopay-errors',
    	showCardTypeIcons: true,
    	cardTypeIconRight: "10px",
    	cardTypeIconTop: "-2px",
    	backgroundColor: "#FFFFFF",
    	layout: "compact",
    	enabledPaymentMethods: ['CARD'],
    	isCountryAndPostcodeVisible: false,
    	errorsDisplay: "HIDE_UNDER_FIELDS",
    	disableUnderline: false,
    }
}
</script>

For the purpose of this exercise, this sample config sets the following options for the iframe:

  • Default language will be English “en” 

  • iframe error field location set to “judopay-errors” as set in (4) above

  • Card Icons will display when the card entry is recognised 

  • iframe Background Colour is White “#FFFFFF” 

  • iframe layout set to compact

  • iframe accepts Credit Card Entry “[‘CARD’]”

  • iframe does not show Post Code entry

  • iframe Errors will not display under the fields

  • iframe will underline the fields and highlight during entry

  1. Create the iframe in a <SCRIPT> tag:

var judo = new JudoPay("yourAPIToken", true);
var payment = judo.createCardDetails('payment-iframe',configMinimum);

Note

The iframe is created in your <SCRIPT> location.

  1. Alter yourAPIToken to match your Sandbox API Token.

  2. true’ lets the iframe know it’s running on sandbox.

    Set this to ‘false’ when you wish to go live and use a ‘live’ API Token

  3. ‘payment-iframe’ is where the iframe will load as defined in step (3) above.

  4. ‘configMinimum’ uses the style called configMinimum as defined in step (5(a)) above.

iFrame.png

Complete customisation of the iframe settings and styles can be found here.

Step 2: Obtain the Payment Promise

Once you have an established Judopay WebSDK iframe and after the consumer has entered valid card details (the iframe handles the validation and errors of this entry), on clicking the Pay Now button (submit-payment-button) you will obtain a promise from Judopay's servers which will return a oneUseToken for use within 30 minutes to transact the payment.

Note

This is a happy path example, and you should enhance this code with try / catch surrounds.

 

The following script:

  1. Adds an action to the payment button.

  2. Checks if the payment method is valid.

  3. Calls Judopay to obtain a oneUseToken. 

  4. It then proceeds to validate the result as having received a oneUseToken.

To setup a payment promise on the Pay Now button:

var paymentPromise = "";
$("#submit-payment-button").click(function(){
   if (judo.getPaymentMethod()=="CARD") {
  	var paymentPromise = judo.createToken(payment);
  	paymentPromise.then(function(result) {
     	if (typeof result.error !== 'undefined') {
        	if (typeof result.oneUseToken !== 'undefined') {
 
            	  	// This is where the token is sent to your back office for payment
         	// request (expanded example below)
 
        	}
     	} 
  	}
   }
}

Step 3: A oneUseToken is sent to Merchant's Server

This example expands on Step 2: Obtain the Payment Promise above, with the source code to handle the oneUseToken and then submit this to the merchant’s server.

  1. Insert this quote into the sample above.

    This is where the token is sent to your back office for the payment request

  2. This sample jQuery calls a php file called handle3.php which will submit the request to Judo and return the result:

$.get("handle3.php",{myToken : result.oneUseToken}, function(data) {

// Code in here to handle the result from the oneUseToken Request will be inserted
// Here and handled in Step 5: Handle the Response from Judopay's Servers
}
);

Step 4: Merchant Server Sends Payment Request to Judopay

This example should be called handle3.php and is the receiving handler from the Step 3: A oneUseToken is sent to Merchant's Server section above.

This example:

  • Receives a oneUseToken from the promise handler step.

  • Submits a £1.00 payment request to Judopay for payment processing using API version 5.7.1

  • Uses gw1.judopay-sandbox.com as the endpoint.

  • For production use the production credentials (APIToken / APISecret) and the endpoint gw1.judopay.com

  • Will return the JSON response received from Judopay's Servers:

<?php
header('Access-Control-Allow-Origin: *');
header('Content-Type: application/json');
 
$OneUseToken = $_GET["myToken"];
 
$userEncode = base64_encode("yourAPIToken:yourAPISecret");
$data=json_encode(
array(
'oneUseToken' =>$OneUseToken,
'yourConsumerReference' =>substr(md5(rand()), 0, 7),
'yourPaymentReference' => substr(md5(rand()), 0, 7), 	
'judoId' => 'yourJudoId',
'amount' => 1.0,
'currency' => "GBP"
));
$headers = array(
Content-Type:application/json',
'Authorization: Basic '.$userEncode,
'API-Version: 5.7.1',
);
$ch = curl_init("https://gw1.judopay-sandbox.com/transactions/payments");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
 
echo $response;
 
?>
  1. Change yourAPIToken:yourAPISecret for your API Token and your API Secret.

    Warning

    IMPORTANT: Do not omit the :

  2. Change yourJudoId for your JudoID.

Step 5: Handle the Response from Judopay's Servers

  1. Extend the handler from the Step 3: A oneUseToken is sent to Merchant's Server section, to handle the response.

This simple example just alerts a Success or Failure response:

$.get("handle3.php",{myToken : result.oneUseToken}, function(data) {
 
   if (data.result=="SUCCESS") {
 	// Handle a Success Result
 	var receiptId = data['receiptId'];
 	// Handle a Failure, you can look the data result for further detail
 	// To add other actions
 	alert(‘Payment Success’ + receiptId);
   } else {
 	alert(‘Payment Failed’);
   }
}
);
  1. Checks if the result returned from Judopay's servers = SUCCESS.

  2. If Success: Alerts Payment Success with the receiptId.

  3. If NOT Success: Alerts Payment Failed.

Receipt Object - SUCCESS

From the Handle the Response from Judopay's Servers section above, the $response will either be a:

  • receiptobject or

  • an ERROR

which you should handle accordingly. This example just echo’s the result from Judopay's Servers.

Example: Receipt Object for a Successful Transaction:

{"receiptId":"615495218204119040",
"yourPaymentReference":"bbd5067",
"type":"Payment",
"createdAt":"2020-08-25T11:38:06.7811+01:00",
"result":"Success",
"message":"AuthCode: 058967",
"judoId":100183086,
"merchantName":"testmerchant",
"appearsOnStatementAs":"APL*/testmerchant ",
"originalAmount":"1.00",
"netAmount":"1.00",
"amount":"1.00",
"currency":"GBP",
"cardDetails":
{"cardLastfour":"6891",
   "endDate":"1220",
   "cardToken":"DgoimaGqpm8ngRKnAl7xgXvFS0zuf3JQ",
   "cardType":1,
   "cardScheme":"Visa",
   "cardFunding":"Credit",
   "cardCategory":"",
   "cardQualifier":0,
   "cardCountry":"FR",
   "bank":"Credit Industriel Et Commercial"},
"consumer":
{"consumerToken":"dQxfNBY5cddXeMhe",
   "yourConsumerReference":"3190912"
},
"riskScore":0,
"threeDSecure":
{"attempted":true,
   "result":"PASSED"},
"externalBankResponseCode":"",
"billingAddress":{}
}

Parameter

Description

receiptId

Unique 18 digit reference for the transaction.

yourPaymentReference

Unique payment reference you provided, or generated if not provided.

type

Type of transaction:

  • Payment

  • Refund

  • Void

createdAt

Date and Time stamp of the transaction.

result

Result of the transaction:

  • Success

  • Declined

  • Failed

  • Error

message

Further details of the result, for example:

  • Auth Code

  • reason for failure

judoId

The judoId the transaction was associated with.

merchantName

Merchant Name.

appearsOnStatementAs

The name the consumer will see on their statement.

originalAmount

Original amount of the transaction.

netAmount

Net amount of the transaction.

currency

Transaction currency.

cardDetails

Array of card details.

cardLastfour

Last 4 Digits of the consumer's card.

endDate

Expiry date of the consumer's card.

cardToken

Unique card token for this card, stored in Judopay's card vault.

Note: This can be used to make token payments in the future.

cardType

Card Type.

cardScheme

Card Scheme.

cardFunding

Card Funding Scheme.

cardCategory

Card Category.

cardQualifier

Card Qualifier.

cardCountry

Card Country of origin.

bank

Bank for the Card.

consumer

Consumer Array.

consumerToken

Unique consumer token to be used in conjunction with cardToken to make future payments.

yourConsumerReference

Unique consumer reference you provided in the originating transaction.

riskScore

JudoShield risk score for the transaction:

  • 0 = Low

  • 100 = High

threeDSecure

3D Secure Array.

attempted

If 3D Secure was attempted.

Boolean.

result

Result of the 3D Secure attempt.

externalBankResponseCode

Any other External Response Codes.

billingAddress

Billing Address.

(If provided in the originating transaction).

Step 6: Redirect the Consumer to the Appropriate Location

As a result of the receiptObject received in Step 5: Handle the Response from Judopay's Servers, you should redirect the consumer accordingly.

For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.

Note

You can store any of the receiptObject details in your own back office systems for recall later.

You could store the:

  1. cardToken

  2. consumerToken

  3. cardDetails

    against the consumer's record and offer a quick checkout option for future transactions.

Using those tokens bypasses the need to enter any card details if required.