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

What is a Token and Secret Pair?

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 which are specific to the sandbox and live environments.


Only sandbox API tokens and test cards will work in the sandbox. Using the wrong tokens and secrets will result in an authorisation failure.

Each token and secret pair will have specific permissions and capabilities, they are not shared between all your apps. You will have to configure each app separately.

For example:

  • JudoPayWebPaymentsPost - Send Web Payment

  • JudoPayApiTransactionsPreAuthsPost - Send PreAuth

  • Enforcing AVS (Address Verification)

  • Enforcing 3DS

For more details on permissions, additional capabilities and viewing your token and secret pair, see Token and Secret Pair.

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

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 permissions, see 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.

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

You can integrate 3D Secure 2: