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.

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 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": "2022-10-06T17:43:21+01:00"


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.30/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>

  1. In your <BODY> add a <DIV> tag where you want the iframe to appear: <div id="payment-iframe" width="100%"></div>

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

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>

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

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

  3. You can apply any CSS styling you wish to this button. <button id="submit-payment-button" name="submit-payment" disabled> Pay Now </button>

  1. 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:

The iframe is created in your <SCRIPT> location.

  1. Alter yourAPIToken to match your Sandbox API Token.

    The parameter is called useSandbox.
    Set to true to use the Sandbox environment.
    Set to false to use the Production environment.

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

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

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


If you want to set the focus to the card number field when the card entry screen appears, add: ‘judokit.createCardDetails(’iframe-container-id', {autofocus: true})'


Step Three: Making a Transaction

When the Web SDK Pay Button is clicked, the invokePayment, or invokePreauth method will be called from the Web SDK.


To make a transaction:

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

  1. The details of the configuration object needs to be set:



  1. Invoke a payment using the paymentSession and configuration:

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


Step Four: Handle the Response

The response will determine whether the consumer is challenged for additional information in order to process the transaction. If the consumer is challenged, the Web SDK takes over and automatically presents the 3D Secure 2 challenge screen to the consumer.

The consumer will enter the required additional information, for example a code or password.


Once the authorisation is complete, the consumer is redirected to the outcome screen.

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


For more information on the response codes, see Codes.

For more information on testing your integration, see Test Scenarios.

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