Judopay Documentation

Getting Started with Judopay

To start integrating with Judopay:

Step 1: Sign up for your Judopay Sandbox Account

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

Sign up for your sandbox account here.


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

Once you have signed up, you will receive your:

  • Token and secret pair

  • JudoId

Step 2: Get Access to your Judopay Dashboard

Get access to your dashboard in the Judopay Portal.

Here you can create your app.

Creating your App

From the Judopay Portal:





From the side menu, select Your apps


The Your apps page appears.

Click the Add app button.


The app configuration page appears.

Enter the name for your app.

For the purpose of this exercise, Documentation Testing App is entered.


To enable pre-configured permissions depending on the kind of app you are creating, select one of the following options:

Native Mobile: Payments using our native Mobile.

Web Payments: Using our hosted re-direct Web Payments solution.

Your Back Office: Using our Server SDKs, or build directly to our API. See Getting Started with our API.


Click Add app


Your new app will appear at the bottom of the list of apps.

You can select the app to view and edit the configuration settings.


Each app has a unique configuration, meaning permissions or feature configurations (such as one-click payments) are not shared between all your apps.

You have to configure each app separately.


For more details about app permissions, see App Permissions.

Important Fields

Before you get started, see the Important key fields that need to be sent between your app and Judopay when making payments:

Unique Judo ID

  • Specific to a merchant or location you wish to pay

  • String of numbers

  • Maximum length 9 characters

  • Format: 100100100

  • Do not include spaces or dashes

Your Consumer Reference

  • Allows you to uniquely identify your customer

  • Must be supplied in a payment request

  • Can be used to help merchants to reconcile

  • Can be used to prevent fraud from occurring through the system

  • All subsequent transactions must exactly match the Consumer Reference as it is case sensitive

  • String field 40 characters in length


We do not recommend using the consumer’s email address. Instead, we recommend you use a Global Unique Identifier (GUID) generated internally by your system.

Due to the GDPR regulations, please avoid using sensitive customer information in free text fields. See ICO - GDPR.

Your Payment Reference

  • Your reference for a payment 

  • Should be unique to protect your customers against duplicate transactions

  • Maximum length 50 characters


With a server side integration, if a Payment Reference is not supplied, any transactions will not be processed.

With our native Mobile SDKs, a Payment Reference is generated and linked to a transaction if one is not supplied.

What is a JudoId?

Your unique JudoId is an important key field that needs to be sent between your app and Judopay when making payments. The JudoId is added to the request body.

Your JudoId is:

  • Specific to a merchant or location you wish to pay

  • Format: 100100100

Token and Secret Pair

A token and secret pair is a method to authenticate and enable access to secure data.


The token is used in conjunction with the secret to authenticate the request.


The secret is the ‘password’ that is used to authenticate against the token. It is known as a token and secret pair because a token is associated with its secret (the pair). Together they work to confirm the identity and authentication of a payment.

Each app has a Token and Secret Pair for Sandbox and Live. 


Only sandbox API tokens and test cards will work in the sandbox.

Using the wrong tokens and secrets will result in an authorisation failure.

Token:Secret App Permissions

You can create more than one set of tokens for a single app, depending on your requirements and app usage. Each token and secret pair will have specific permissions, they are not shared between all your apps.

You will have to configure and set the following permissions separately for each app :

  • JudoPayTransactionsGet - Retrieve Transactions

  • JudoPayApiTransactionsPaymentPost - Send Payments

  • JudoPayApiTransactionsRefundsPost - Send Refunds

  • JudoPayWebPaymentsGet - Obtain Web Payment Token

  • JudoPayWebPaymentsPost - Send Web Payment

  • JudoPayApiTransactionsPreAuthsPost - Send PreAuth

  • JudoPayApiTransactionsRegisterCardPost - Register Cards  


It is not recommended to have all permissions on the same APIToken/APISecret. For example, refund should be a special token for back office use only.

Token:Secret Additional Settings

At the APIToken/APISecret level, additional settings can be initiated:

  • Enabling Webhooks

    Contact customer support to set up the following features:

  • Enabling WebPayments

  • Enforcing AVS (Address Verification)

  • Enforcing 3DS

  • CV2 (Optional)

Token and Secret Permissions

Each Token and Secret pair will have specific permissions configured.


Double check these permissions before using the Token and Secret.

Each app has a Token and Secret Pair for Sandbox and Live.

To view the Sandbox Token and Secret in the Judopay Portal:

view sandbox token and secret




From the side menu, select Your apps

Select the app to view the Token and Secret credentials


Select Sandbox tokens to see both the Token and Secret for the Sandbox Environment.


The Sandbox Token information is displayed.

You can:

View the Token | Secret | View and Edit Permissions | Disable the token | Add a new Sandbox token


A live Token and Secret will only be visible within the app once your account is activated.

3D Secure 2

The Payment Services Directive (PSD2), has introduced a new regulatory requirement: Strong Customer Authentication (SCA). The aim of the SCA is to add an increased layer of security for card not present transactions, when making mobile and online payments.

For more information, see Upgrading to 3D Secure 2 (EMV 3D Secure).


The deadline for PSD2 implementation for all the European Union countries members was 31st December 2020.

The deadline for SCA implementation for UK merchants has been extended to 14th March 2022.