Quick Start


Quickly integrate and perform a test payment with Judopay.

The following example takes you through the steps to quickly integrate and perform a test card payment using Judopay’s Web SDK.

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.


Start Integrating with Judopay

To start integrating with Judopay:

Step One: Sign up for your Judopay Sandbox Account

You need your sandbox account so you can process test transactions while developing your app.

An app is a Judopay term and relates to your API credentials.

Once signed up, you will receive your:

  • TokenSecretAuth

    • The token and secret pair

    • Specify your token in Username and secret in Password

  • JudoId

Ensure Judopay has enabled 3D Secure in your sandbox account. If this is not enabled the test transaction may appear successful without following the correct payment flow.
Contact ​Customer Support​​ to set this up.


Step Two: Get Access to your Judopay Dashboard

Get access to your dashboard in the Judopay Portal where you can create your app.

For more details, see Creating your App


Perform a Test Payment

The following guide is a full working example for use with Judopay's Web SDK.

When authorising /payments or /preauths it is recommended to use paymentSession.

Step One: Create a paymentSession

Make sure you are using Judopay's API version or higher.


Important to Consider:

  • The paymentSession can be used for up to three transaction attempts for the same transaction.

    • If the block duplicate transactions permission has been applied on your API tokens, the paymentSession can only be used for one transaction attempt.

  • A payment session can be used again to re-submit a failed transaction attempt.

  • Once a transaction attempt is successful, the paymentSession can no longer be used even if there are any remaining attempts available.

  • The paymentSession will expire in 30 minutes, unless an ExpiryDate is set in the /paymentsession request body.

    • The expiry date must be within one year: "ExpiryDate": "2023-10-06T17:43:21+01:00"

    As soon as the payment session is used for the initial transaction attempt, this will initiate the 30 minute expiry time.


Make a HTTP POST Request: /paymentsession

For the full schema details and descriptions, see Transaction API /paymentsession


Response Model

Payment-Session - Response Reference:


Your backend server should store the paymentSession response reference returned by Judopay's API.

Use this reference from the response to populate paymentSession when calling /payments and /preauths from your front-end client.

See Step Three: Making a Transaction.


The following parameters need to remain consistent between the /paymentsession requests and the /payments and /preauths requests, otherwise the transaction will fail:

  • YourPaymentReference

  • YourConsumerReference

  • JudoID

  • Currency

  • Amount

This is used to cross reference the validity of the transaction.


Step Two: Add the Payment Form to your Website


Create and customise the Judopay Web SDK iFrame:

  1. Add the code snippet in your web page <HEAD>: <script src="https://web.judopay.com/js/0.0.42/judopay.min.js"></script>

    To automatically receive non-breaking changes, you can pin to the minor version (0.0) rather than the current patch version (0.0.42).

    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>

    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.

    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>

    For more information on all errors that can be returned, see Displaying Payment Form Error Messages.

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

    Make sure you have set:id="submit-payment-button" . This is required to perform form validation where the Pay button will be greyed out until all the information has been entered.

    <button id="submit-payment-button" Pay Now </button>

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

  2. In your <BODY> define the iFrameConfiguration object. This is used to customise the look and behaviour of the iFrame.

    For more information on customising the iFrame, see Customising your Web SDK Integration.


    An example of an iFrameConfiguration object:

The iframe is created in your <SCRIPT> location.


See below for more details on the parameters that create the iFrameConfiguration object:


  1. Create an instance of the Judopay Web SDK: var judo = new JudoPay("yourAPIToken", true); //initialize library
  • Alter yourAPIToken to match your Sandbox API Token

  • The second parameter is called useSandbox

    • Set to true to use the Sandbox environment.

    • Set to false to use the Production environment.

  1. Create the iFrame in the <div> tag: var payment = judo.createCardDetails('payment-iFrame', iFrameConfiguration)

    • 'payment-iFrame': The <div> id where the iFrame will be rendered, in step (2) above.

    • iFrameConfiguration: The object defined to customise the look and behaviour of the iFrame, in step (5) above.


Step Three: Making a Transaction

To make a transaction:

  1. Define the paymentConfiguration object for the payment or preauth:

Ensure the details used when creating the paymentSession match the values set in the following configuration:


See below for more details on the parameters that create the paymentConfiguration object:


  1. In a function, add the invokePayment call.

    This will invoke a payment using the paymentSession and paymentConfiguration


To invoke a preauth, change the above code to .invokePreauth

  1. To call the function (in step 2 above) to invoke the payment or preauth, add the onclick attribute to the payment button <div>:

    <button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>


Step Four: Handle the Response

Once the authorisation is complete you will receive either:


The consumer should be redirected to the outcome screen and the response/error should be handled accordingly.

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


For more information on the response codes, see Codes.


Putting it all together to display the payment form and make a transaction:


Testing and Customising your Integration

For more information, see Testing your Integration.

For more information on customising your integration, see Customising your Web SDK Integration.