API reference

The Judopay REST API is the core of our payment processing platform – it powers our mobile SDKs and makes it easy for you to integrate payments into your backend. Our API is designed with industry standard best practices, including JSON responses and HTTP response codes for errors.

If you want to integrate Judopay into your app we recommend using the built in API clients in our SDKs rather than creating your own API client from scratch.

To enable you to thoroughly test your integration we provide a sandbox environment for performing test payments. When you are ready to go live, please ensure that you are using the live token and secret from the Judopay dashboard.

Please note: In order to successfully go live and give your customers the best experience possible ensure that all fields in this API reference are implemented as outlined in the reference below.


Request fields

PropertyTypeNotes
yourConsumerReference string
up to 40 
required
A Consumer Reference must be supplied in a payment request. It should be an identifier that allows you to easily and uniquely identify your customer. The Consumer Reference can then be used to help merchants to reconcile as well as prevent fraud from occurring through the system.

Please note: We do not recommend using the consumer’s email address as this could leave you open to an attack. Instead, we recommend you use a GUID (Global Unique Identifier) generated internally by your system. After a Consumer Reference has been created for the first time, you will need to ensure on subsequent transactions that the Consumer Reference is an exact match (case sensitive). Consumer Reference is a string field that has a maximum of 40 characters.
yourPaymentReference string
up to 40 
required
Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions.

Please note: With a server side integration, if a payment reference is not supplied, the transactions will not be processed. With our native SDKs, a payment reference is generated and linked to a transaction if one is not supplied.
yourPaymentMetaData object
See ‘Notes’
Allows you to populate additional information you’d like to have associated with a transaction. This information is carried across on the receipt that Judopay provides, which can help you reconcile transactions. The property name and value are both limited to 50 characters, and the whole object cannot be more than 500 characters.
judoId string
6 to 10 chars 
required
Judopay supplies you with a unique Judo ID (e.g. "123-456" or "654321") that is specific to a merchant and/or location you wish to pay.
amount float
required
The amount to process, to two decimal places. 

Please note: If you are looking to process currencies that use a different structure other than two decimal places, please contact Judopay for support.
cardNumber string
16 to 19 chars 
required
The card number should be submitted without any whitespace or non-numeric characters
expiryDate string
5 chars 
required
The expiry date should be submitted as MM/YY
cv2 string
2 to 4 digits 
required
CV2 from the credit card, also known as the card verification value (CVV) or security code. It's the 3 or 4 digit number on the back of your credit card
currency string This property identifies the currency of this transaction. This can be any ISO 4217 alphabetic currency code such as GBP, USD or EUR. We support different currencies such as AUD, SEK, CAD, NOK, BRL, CHF, CZK, DKK, HKD, HUF, JPY, NZD, PLN, ZAR and SGD
clientDetails string
5 chars 
required
What we use to tie the device information to a particular request. Using the SDK you’ll be able to retrieve the clientDetails that allow JudoShield to track a user’s Device DNA for fraud protection
consumerLocation consumerLocation

The location of the card holder when making the transaction
mobileNumber string
10 to 13 chars
required
if submitted must be the consumers valid UK mobile number (starting "+447" or "07")
emailAddress string
150 chars
required
A valid email address for the consumer
StartDate string
5 chars
required
For Maestro cards, the start date should be submitted as MM/YY
IssueNumber string
1 to 2 digits
Issue number from the Maestro card. It should be a number between 1 and 2 digits (from 0 to 99), located normally on the front of your card
cardAddress
line1 string
up to 150
The registered address for the card
line2 string
up to 150
The registered address for the card
line3 string
up to 150
The registered address for the card
town string
up to 150
The registered address for the card
postCode string
up to 10
The registered address for the card
consumerLocation
latitude float

The consumer's current location
longitude float

The consumer's current location

Response fields

If you are looking for information on error messages please see the Error messages section of the API.

PropertyTypeNotes
receiptId integer
64-bit signed (up to 19 chars)
Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string
up to 40
The original reference for this payment, which was sent with the request
type String Enumeration "Payment" or "Refund"
createdAt date An ISO8601 formatted date and time (including time zone offset).
result string The result of this transactions, this will either be "Success" or "Declined"
message string A message detailing the result
judoId string
6 to 10 chars
Judopay supplies you with a unique Judo ID (e.g. "123-456" or "654321") that is specific to a merchant and/or location you wish to pay
merchantName string
up to 250 chars
The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string
up to 30 chars
How the Merchant will appear on the Consumers statement
amount decimal This is the original value of this transaction before refunds
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
currency string This property identifies the currency of this transaction. This can be any ISO 4217 alphabetic currency code such as GBP, USD or EUR
yourPaymentMetaData object
see ‘Notes’
Allows you to populate additional information you’d like to have associated with a transaction. This information is carried across on the receipt that Judopay provides, which can help you reconcile transactions. The property name and value are both limited to 50 characters, and the whole object cannot be more than 500 characters
cardDetails cardDetailsObject Information about the card used in this transaction
consumer consumerObject details of the Consumer for use in repeat payments
metadata
any string the data you want to attach to this payment
cardDetailsObject
cardLastFour string
4 chars
The last four digits of the card used for this transaction
endDate string Expiry date of the card used for this transaction formatted as a two digit month and year i.e. MM/YY
cardToken string
up to 50 chars
Can be used to charge future payments against this card
cardType integer
32-bit signed
numbertype
0 Unknown
1 Visa
2 Mastercard
3 Visa Electron
4 Switch
5 Solo
6 Laser
7 China Union Pay
8 Amex
9 JCB
10 Maestro
11 Visa Debit
12 Mastercard Debit
13 Visa Purchasing
14 Discover
15 Carnet
16 Carte Bancaire
17 Diners Club
18 ELO
19 Farmers cards
20 Soriana
21 Private Label Card
22 Q Card
23 Style
24 True Rewards
25 UATP
26 Bankard
27 Banamex costco
consumer
consumerToken string
up to 50 chars
Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions.
yourConsumerReference string
up to 40 chars
Details of the Consumer for use in repeat payments. You will need to ensure on subsequent transactions that the consumer reference is an exact match (case sensitive). Consumer Reference is a string field that has a maximum of 40 characters.