Judopay Documentation



Under no circumstances should merchants store or log any credit card details unless they are fully PCI-DSS compliant. This falls under your responsibility to ensure you do not produce code which circumvents our toolkits. We do not accept any liability for this.

3D Secure Overview

3D Secure (3 Domain Secure) is an authentication service for card payments that acts as an additional fraud prevention and security layer. It aims to confirm the consumer’s identity before processing an online purchase, acting in a similar way to Chip and PIN reducing exposure to fraud for both consumer and merchant.

During the checkout process, if a card is enrolled with 3D Secure, it can be used to verify the authenticity of the transaction.3D Secure is also known as:

  • Verified by Visa (VBV)

  • MasterCard Secure Code (MSC)

  • Discover ProtectBuy

Typical implementations of 3D Secure allow consumers to create a password associated with their card.

A transaction using VBV, MSC or DPB redirects the consumer to the authorisation website of the card’s issuing bank. On this website, the consumer is expected to provide the requested characters from their password, in order to authorise the transaction.


The 3D Secure password authorisation is performed by the issuing bank, so it is not possible to change or customise this page.

Since the password is not stored on the card, it reduces the risk of card fraud owing to a stolen card or card details.

The sandbox environment displays a 3D Secure simulator page that allows you to simulate a success or decline 3D Secure result.


You should check how your app responds to the different results.

3D Secure

Integrating 3D Secure


  • Ensure you have an API application key (token and secret) enabled for 3D Secure. 

    It is assumed you have a server implementation and are using mobile SDK’s or iFrame.

    If you are using our hosted web payments redirect to take payments, ensure your account is enabled for 3D Secure. The majority of the integration will be handled for you.

Step One

Using your pre-configured 3D Secure application key, make a payment request to our API from your server:

  • Card Payment

  • Token Payment

  • Token Preauth

  • Preauth

Step Two

If the card is enrolled to support 3DS, the response will be set to Requires3DSecure.

  • acsURL

    The URL used to redirect the consumer to 3D Secure.

  • md

    An encrypted blob of information Judopay needs in order to resume the transaction.

  • PaReq

    The Payment authorisation request. A unique ID to identify the 3D Secure request.

Step Three

The POST request needs to include the following fields (case sensitive):

  • PaReq

    The Payment authorisation request. A unique ID to identify the 3D Secure request.

  • MD

    An encrypted blob of information Judopay needs in order to resume the transaction.

  • TermUrl

    The termination URL. This is the location the ACS server will return the consumer to in the event of either success or failure of the 3D Secure authorisation.

    The consumer will be redirected to the 3D Secure screen, to verify the transaction.

Incorrect usage to your TermUrl will produce a lack of response, or incomplete data in the ACS URL response.

To complete the 3D Secure transaction PUT to receiptID method.

On the client side (web browser or web view for in-app journeys), a POST method needs to be made to the acsURL received from Judo’s API. See Step 2.

Step Four

Once the consumer has completed the 3D Secure authentication, they will be navigated to the TermURL supplied in the POST request.

Not all 3DS service providers return the MD value in this callback.

  • PaRes

    A Base64 encoded, encrypted message with the results of the 3D Secure authentication.

After completing 3D secure it will return to TermUrl which should have PaRes, and in most cases the MD, as form parameters.

Step Five

Use PaRes and MD to complete the 3D Secure transaction.

Call the Complete3DSecure API method.

This sends a PUT request to: 


where receiptId is the original receiptId from Step Three.

Example body request:

{     "PaRes": "response in step (5)",     "Md": "response in step (5)" }

Step Six

Judopay's API will reply with a transaction receipt, including the outcome of the transaction in the Result property.

Result Description

  • Success: The transaction has been successfully processed.

  • Declined: The transaction was declined by the issuing bank, or the 3D Secure process was not successfully completed.

  • Error: There was a problem processing the PUT request. Please confirm you forwarded the complete PaRes and MD values without modification.

3D Secure - 2.0

What is Strong Customer Authentication?

Strong Customer Authentication (SCA) is part of the second Payment Services Directive (PDS2), a European regulatory requirement to help improve the security of online payments and reduce fraud.

Once SCA comes into effect, in order to collect payments additional authentication is required in your checkout flow.

SCA requires authentication to use at least two of the following three aspects:

  • something the customer knows (e.g. password or pin)

  • something the customer has (e.g. phone or hardware token)

  • something the customer is (e.g. fingerprint or face recognition)

Are there Exemptions to SCA?

Under this new regulation, specific types of payments that are considered to be low-risk may be exempted from Strong Customer Authentication. 

Note that this is subject to the issuer’s decision; they can reject any request exemptions if they feel these fall foul of their risk analysis processes. 

Possible exemptions include:

  • Low risk transactions: where a bank’s overall fraud rates for card payments do not exceed:

    0.13% to exempt transactions below €100 (or local equivalent amount where relevant)

    0.06% to exempt transactions below €250

    0.01% to exempt transactions below €500 Transactions below €30

    these will be considered 'low value' and may be exempt. 

However, banks will need to request authentication if the exemption has been used five times since the cardholder’s last successful authentication, or if the sum of previously exempted payments exceeds €100 Fixed-amount subscriptions - this can apply when the customer makes a series of recurring payments for the same amount, to the same business. 

SCA will be required for the customer’s first payment but subsequent charges may be exempt. MOTO (Mail Order Telephone Order) payments - card details collected over the phone

What is 3D Secure 2?

3D Secure allows shoppers to create and assign a password to their card that is then verified whenever a transaction is processed through a site that supports the use of the scheme. 

3D Secure 2.0 (3DS 2.0) is the latest update to this, adding a new, stronger standard for customer authentication that meets the new SCA requirements. 

This new version offers a better user experience and helps to minimise some of the friction the authentication adds to the checkout flow.


Judopay is implementing a complete 3D Secure 2.0 journey, fully managed by our SDKs. This means there is no requirement for developers to handle a 3D Secure 2.0 transaction.

3D Secure Integration Questions

What changes do I need to make to my Judopay mobile app implementation?

  • I already have 3D Secure 1.0 

    • To enable 3D Secure 2.0 and above you will simply need to update your mobile SDKs.

  • I do not have 3D Secure 1.0

    • You will need to amend your payment flows to include 3D Secure. 

    • We recommend you implement 3D Secure 1.0 to ensure you are compliant and can upgrade to 2.0 when we release our updated mobile SDKs.

What changes do I need to make to my Judo web SDK implementation?

  • I already have 3D Secure 1.0

    • We will make the changes in the background and automatically update you to 3D Secure 2.0.

  • I do not have 3D Secure 1.0

    • You will need to amend your payment flows to include 3D Secure.

    • We recommend you implement 3D Secure 1.0 in the interim so you can automatically benefit from the upgrade when it comes. 

    • However, if you want to wait to make the updates directly to 3D Secure 2.0 later in the year you can.

What changes do I need to make to my Judopay Web Redirect implementation?

Check that your Judopay account is configured for 3D Secure 1.0. If you’re unsure, please contact our customer service team. 

Similar to Judo web SDK we will handle the rest by pre-populating the required fields in the background on your behalf.

When can I start implementing the required changes so I’m ready for 3D Secure 2.0?

Judopay server and mobile SDKs are 3D Secure 2.0 ready. 

You can start to integrate now.

Code Security

Code obfuscation is the act of making source code difficult for a human to read.

Whilst it is not impossible to reverse engineer obfuscated code, the goal is to make it difficult or economically unfeasible.


We recommend all Android apps are obfuscated.

In your app:

  • Go to the build.gradle file 

  • Add: minifyEnabled true

  • Enable default file: proguardFiles getDefaultProguardFile(‘proguard-android.txt’) 


Generally iOS apps are well protected, as the code is compiled into machine code before the app is released to the Apple App Store.

Machine code contains less meta-data around the code, making decompilation significantly harder, therefore code obfuscation is not usually required.

Communicating with your Server

In line with industry best practice, we recommend you use TLS 1.2 for all communications between your app and your server.

It is possible for a hacker to override the CA certificate of a device and therefore intercept communications on the device. 

In order to prevent this type of man-in-the-middle attack, we recommend using certificate pinning.


We recommend using the OkHttp and Retrofit libraries for communicating with your server.

This simplifies the networking layer of your app and supports SSL pinning out of the box. 

To enable SSL pinning, provide the certificate details when constructing the OkHttp instance:

OkHttpClient client = new OkHttpClient.Builder(
        .certificatePinner(new CertificatePinner.Builder()
               .add("example.com", "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=")


Example of iOS SSL pinning:

API Application Permissions

For security, only enable the absolute minimum permissions required for your mobile app and your backend. 

Follow the Set Permissions instructions to ensure you are set up correctly.


Security Updates

Platform libraries are updated every few weeks, we recommend that you monitor these releases for major security updates:

  • https://developers.google.com/android/guides/releases

  • https://security.googleblog.com/

  • https://support.apple.com/en-gb/HT201222

We recommend you publish a new version of your app after each major security release, or at least once every 6 months.

Updating the Judopay SDK is also recommended on the same schedule – we will update our code based on latest security updates, so it is important that you stay up to date.

Follow the setup instructions for integrating the latest mobile SDKs:

  • Android

  • iOS Swift

  • iOS Objective-C

Additional Steps

  • App Permissions on Android Devices 

    The Judopay SDKs do not require any specific permissions, but if you enable certain permissions on Android we are able to extract more information from the device to use in fraud detection and prevention.

    In the Android manifest, add the read phone state permission:

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

  • PCI-DSS Scope - Building your UI

    If you are building your own app checkout UI, you are handling card details and will fall within the full scope of the PCI-DSS compliance rules.


JudoShield is our mobile fraud prevention tool – a risk engine that collects, analyses and returns a ‘Risk score’ between 0 and 100 for each transaction.


This is based on transactional data and mobile device signals – captured via Judopay’s SDKs.

The Risk score determines if a transaction is Allowed, Blocked or sent to 3D Secure.

If the Risk score returned reaches the Block threshold, the transaction and/or user is flagged, preventing them from completing this transaction or any future transactions.


  • Works together with our seamless in-app payment SDKs to fully protect your business and customers – from the first line of code, to the end of every transaction.

  • Enables intelligent and proactive management of transaction risks, minimizing fraud and reducing chargebacks.

  • Runs quietly in the background, its rules and enforcements can be enabled when it makes sense for the business to do so.

  • Provides smart machine-learning capability that help businesses continuously fine-tune their fraud prevention strategy based on what makes sense for their customers and industry.

How JudoShield Works

JudoShield is a mobile-specific security toolkit module that combines business rules with machine learning to monitor and block fraudulent transactions.

Based on your appetite for risk you have the option to configure your Block threshold by contacting our team to determine the threshold that will allow, block or send a transaction to 3DS verification.


JudoShield captures data from the transaction and device signals via Device DNA™.

This collection of data is then processed and calculated using machine learning algorithms to return the Risk score.

Set Up Device DNA™

Device DNA™ protects your app from fraud in real-time and enables Judopay to capture the data and device signals at the time of the transaction.

Device DNA™ - Mobile and your Server Side Integration

If you are making transaction requests initiated from your backend, you must first capture the details below from the device at the time of the transaction and pass them in your call to the Judopay API:

  1. Register card – Consumer registers their card in your app.

  2. Response with tokenized card – Judopay will pass back the tokenized card information.

  3. Save tokenized card – You can send these tokens to your backend.

  4. Device DNA™ – You send the device identifier and signals to your backend with each transaction request.

  5. Token payment – Perform a payment using the token and the Device DNA™.


    Example of the deviceIdentifier:

    { "clientDetails": {"key": "m815g6LdYB973ks9DbA==", "value": "fjfjLluVOT0wJ7cMO8vv00qsULrtd6Osio4Ra0mwKEpdK7YsbA==", "deviceIdentifier" : "77dc2ee3-8d78-4051-b2ad-fb99e742d53d" } }

To ensure the Device DNA™ is sent:

  1. Depending on your mobile app, follow the getting started guide for integrating Device DNA™ for iOS or Android.

  2. With the deviceIdentifierkey and value returned, send these to your API.

    If you are using the .NET, PHP or Ruby SDK, ensure you have populated the API reference fields.

    If you are building directly to our API, ensure you have populated the API reference fields.

  3. Include the DeviceDNA fields in the clientDetails model when performing a transaction.

    If you are using the server side SDKs, see the guides for Server SDK - .Net or PHP.

    If you are building directly to our API, see API Reference.

Device DNA™ - Mobile only Integration

If you are using the mobile SDKs to perform all transactions, Judopay will automatically collect and send the appropriate data.

  1. Register card – Consumer registers their card in your app.

  2. Response with tokenized card – Judopay will pass back the tokenized card information.

  3. Save tokenized card – The tokenized card is saved to the device.

  4. Token payment – Perform a payment using the token with Device DNA™ captured automatically.

Device DNA™ is not available for the Xamarin SDK.