Setup

This section contains all the information and actions you will need for a successful integration. Please consider every section and complete what is relevant to your implementation. By following these steps your app will be secure and frictionless for you and your customers.


Getting started

Accept simple and secure payments in your app with our SDKs. Access the sandbox environment via our dashboard to add your app and run test transactions. Follow the link below and we’ll send you a link with your login details.

Get sandbox access


Dashboard

Here is a summary of what you can do on the dashboard.

  • Create and configure your apps.
  • Access your tokens and secrets.
  • Find links to our SDKs and documentation.
  • Access test card details for Visa and Mastercard.
  • View your transactions and process refunds.

Dashboard overview:

  1. Overview’ provides an overview of the account, recent live transactions, account balance and previous transfers.
  2. History’ allows users to view transactions in both environments (sandbox and live), search for specific transactions using a specific receipt ID, last 4 digits of the card or consumer reference, create a filtered view of transactions, and export transactions (csv format). From here you will also be able to refund transactions.
  3. Balance provides a more detailed view of the account’s balance, including what is available now (total payments and fees, refunds, account charges, account credits and total available now) and what will be available soon to transfer to a designated bank account, as well as showing records of all past transfer activity.
  4. Settings provides the Judo ID, transaction fees and funding delay for that particular account, additional account details and options, and transfer details where is listed the designated bank account and the transfer frequency set.
  5. Your apps’ Once you have configured your app in the ‘Developers’ section this view is used for configuring your app and access to tokens and secrets.
  6. Tools’ is where developers can find the links to download our SDKs, test card details for sandbox environment and logs to check transaction results from the API.
  7. ‘Activate account’ includes a registration form to complete to activate your account when you are ready to go live (after you have completed all steps in your ‘Getting started’ guide for your project).
  8. Questions contains a list of frequently asked questions.
  9. Live chat support is available in our office hours, Monday to Friday from 9am to 6pm.
  10. Contact provides a form to get in touch with Judopay customer support for your general inquiries.

%MCEPASTEBIN%

Create an app

You can easily add new apps in the ‘Developers’ section on the dashboard.

To add an app, please follow the steps below:

i.e. If this is your first app, you will see the app creation page (see step 2). If you are creating an additional app, go to ‘Your apps’ and click on the ‘Add an app’ button.

  1. Name your app and a select a pre-configuration based on the type of app you are setting up (native app, web payments or back office). This will help auto-select some permissions for your app.
  2. Click the ‘Add app’ button. You will see the new app listed within the ‘Your apps’ section.

If you have questions about this process, contact us.

Note: Please be aware that each app has a unique configuration, meaning that permissions or feature configurations (such as one-click payments) are not shared between all your apps. You have to configure each app separately. Learn more about permissions.


Access token and secret

Each app created is listed in the dashboard under the ‘Your apps’ section. Each app has its own set of sandbox and live token and secret. A live token and secret section will only be visible once your account is activated. If you are ready to go live, see Activate your account). You can create more than one set of tokens for a single app, depending on your requirements and app usage.

Where to find the set of tokens and how to create a new set of credentials:

  1. Visit your list of created apps in ‘Your apps’ section on the navigation menu.
  2. Select the app you want to see the set of credentials (token and secret) for.
  3. Select ‘Sandbox tokens’ to see both token and secret for sandbox environment. If your account is activated (live and ready to process live transactions), then you should see the 'Live tokens' section as well.
  4. If you want to create additional sets of credentials, click the ‘Add (Sandbox / Live) token’ button in this section. Please be aware that each set of tokens has its own permissions configuration, we recommend to double check the permissions before using the token and secret.

If you have questions about this process, contact us.


Set permissions

It's important to set certain limitations on your app in order to boost its security. Permissions allow your app to accept and process specific endpoints or payment types when it’s used.

Each token set related to an app has its own unique permissions. You should ensure you only enable the absolute minimum permissions required for your mobile app.

Permissions can be edited and changed by following the steps below:

  1. In the dashboard go to your list of created apps in the ‘Your apps’ section on the navigation menu. If you haven’t added an app yet or are adding a new app, please select the pre-configuration you require – Native, Web payments or Server side – when you add your app (this will add the default permissions for your app type).
  2. To edit permissions, select the app you want to see the set of credentials (token and secret) for.
  3. Selected ‘Sandbox tokens’ or ‘Live tokens, depending on the environment you want to set permissions for. The Live token section only appears if your account is activated (ready to process transactions in a live environment).
  4. See the ‘Permissions’ title below the token and secret. Click ‘Edit’ for the set of tokens that you want to modify permissions for. A new window will appear where you can select or deselect permissions. By default native apps have the following permissions set: ‘Make Payments’, ‘PreAuth Transactions’, ‘Register Card Transactions’. If you only perform payments from your backend, see below.
  5. Save’ the changes and test to validate that the changes took effect.

If you perform payments only from your backend:

  • For the app that you created in the Judopay dashboard, you should enable only the ‘Make Payments’ permission.
  • For your iOS or Android app you should create a separate app in the dashboard with only the ‘Register Card Transactions’ permission enabled.

If you have questions about this process, contact usPlease read the ‘Secure your mobile app’ section in order to safeguard your app against fraudulent behaviour.


Webhooks

*The webhooks service is optional for your integration.

Webhooks are an optional secure service provided by Judopay that you can use to notify your system when a transaction/event has taken place.

Using webhooks means you can chose not to pull information from the Judopay API for every event.

The events you can use webhooks for are:

  • Card payments · Charge a card using a card’s full details (16-digit card number, expiry date and CV2).
  • Pre-authorizations · Reserve funds on a card.
  • Collections · To collect the funds you’ve previously reserved with a pre-authorization.
  • Refunds · Process a full or partial refund to the customer.


How to enable webhooks:

  1. Sign in to the dashboard.
  2. Select ‘Your apps’ in the ‘Developers’ section.
  3. Select one of your saved apps.
  4. Select ‘Webhooks configuration’.
  5. Enable webhooks for your required transaction type(s) and add your webhooks URL.
  6. Click ‘Save webhooks’.
  7. In the ‘Add authentication’ section that appears, click the ‘Add authentication’ button and confirm this again in the in the pop-up dialog. The username and password will be combined with a colon separating them. This will then be encoded using Base64.
  8. 8. Your will be able to see your unique username and password for authentication.
  9. Click ‘Save webhooks’ again. Webhooks will now be authenticated using this method.

Judopay will send this username and password along with every request.

Note: If you have already set up webhooks without authentication, it will not work until you add the authentication into your backend.


Web payments

*Web payments do not apply for ‘Mobile and your server side’ or ‘Mobile only’ integration.

If you are planning to you use our light-weight hosted web payments option, please follow the steps below:

  1. Sign in to the dashboard.
  2. If you haven't added an app yet, create an app. If you already have added your app, select the one you want to use for web payments in the ‘Your apps’ section, then access the ‘Web payments configuration’ section.
  3. Now tick the ‘Enable Web payments (hosted redirect web payment)’ option, and specify both the ‘Success’ and the ‘Failure’ URLs. This is where your customer will be redirected once the payment process is completed, depending on the transaction result.

Note: This has to be done separately for each web payments app. In order to prevent browser’s pop-up messages warning the consumer about insecure connectivity with these URLs, both success and failure URLs should use the https protocol.

If you are aiming to host web payments with an app, please note that redirects slow everything down. Also user interfaces that don’t match your app make your customers feel unsafe thus lowering your conversion rate. Native apps offer customers an optimal checkout experience that is simple, frictionless and secure.


Secure your mobile app

At Judopay, security is integral to what we do. It’s our top priority that our customers’ payments are protected. The purpose of this guide is to help you and your customers to build a secure app.

Required steps:

Additional steps:


Required steps:

Credentials

Your Judopay credentials are what allow you to perform transactions, it is therefore vitally important that you protect them from falling into the wrong hands.

In general when embedding credentials in the app it is relatively easy to decompile an app and get at the source code. Hard coded strings are especially easy to extract, so we recommend that you do not directly paste the credentials, for example:

Judo judo = new Judo.Builder()
   .setApiToken("xxxxxxxxxxxxxxxxxx")
   .setApiSecret("xxxxxxxxx")
   .setEnvironment(Judo.SANDBOX)
   .build();

Instead we recommend that you define a set of variables in an unrelated part of the application and pass the variables into the initialization – the variable names will be obfuscated assuming you use an obfuscation tool:

Judo judo = new Judo.Builder()
   .setApiToken(token)
   .setApiSecret(secret)
   .setEnvironment(Judo.SANDBOX)
   .build();

To further enhance security we recommend that you define several variables for both the token and secret, and split these values into several parts, for example:

var tokenPart1 = "xxxxxxxx";
var tokenPart2 = "xxxxxxxxxxxxx";
var tokenPart3 = "xxxxxxx";
var secretPart1 = "xxxxxxxxxxxxx";
var secretPart2 = "xxxxxxx";
initialiseJudo(tokenPart1 + tokenPart2 + tokenPart3, secretPart1 + secretPart2)

Breaking the string into parts will help the obfuscation process, making it harder for a human to understand the importance of the variables. You should also make efforts to define the variables in various locations in your app to make it as hard as possible to piece together.

For Android
Don’t put credentials in strings.xml – values placed here are stored in clear text, this is extremely vulnerable from a security perspective.

For iOS
The best practice for storing credentials is in the keychain. This is stored securely and is only available to the app vendors.

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.

For Android
Due to the nature of Android apps running on Java and Java bytecode being relatively easy to decompile, we recommend that all Android apps are obfuscated.

  1. Go to the build.gradle file of app.
  2. Enable code minification by adding minifyEnabled true.
  3. proguardFiles getDefaultProguardFile(‘proguard-android.txt’) to enable the default one.

See here for more details. For more details on ProGuard, or the paid version DexGuard, see here.

For iOS
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 that 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.

For Android
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=")
.build())
.build();

For iOS
Example of iOS SSL pinning.

Device DNA™

In order to protect your app from fraud you must setup Device DNA™, an essential component of JudoShield. It enables Judopay to capture data from the transaction and the device to protect you from fraud in real time. Follow the instructions in Device DNA to protect yourself from fraud.

API application permissions

For security, only enable the absolute minimum permissions required for your mobile app and your backend. Follow the instructions in Set permissions 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:

We recommend that 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 instructions for integrating the latest mobile SDKs:

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 for building your own UI

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

Judopay’s Out-of-the-box UI comes with built-in checks and security features, including data and address validation, real-time error detection and 3D Secure for a frictionless card data capture. This minimizes PCI compliance and allows you to focus on developing other areas of your app.


JudoShield

What is JudoShield?

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 (learn more about 3DS). 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.

In a nutshell, JudoShield:

  • 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 does JudoShield work?

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.

JudoShield and your Terms and Conditions

We recommend you mention what information you will be collecting and how you intend to use it (in this case for the purpose of fraud protection) in your Terms and Conditions.

The next section will guide you through JudoShield’s setup and the information you will need to provide to us for all payment requests.


Device DNA™

In order to protect your app from fraud you must setup Device DNA™, an essential component of JudoShield. It enables Judopay to capture information about the mobile device to protect you from fraud in real-time.

Device DNA™ · Mobile and your server side integration

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

Note: For JudoShield to work with the ‘Mobile and your server side’ method, you will need to integrate Device DNA™ as described in the guide below.

  1. Register card – Customer 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 then send these tokens to your backend.
  4. Device DNA™ – You send the device identifier and signals to your backend with each payment request.
  5. Token payment – Perform a payment using the token and the Device DNA™.

Follow the steps below to ensure the Device DNA™ is sent:

  • Depending on your mobile app, follow the getting started guide for integrating Device DNA™ for iOS or Android.
  • With the deviceIdentifier, key and value returned, send these values up to your API.
    • If you are using the .NETPHP or Ruby SDK, please ensure that you have populated the API reference fields.
    • If you are building directly to our API, please ensure that you have populated the API reference fields.
  • Include the DeviceDNA fields in the clientDetails model when performing a payment.
    • If you are using the server side SDKs, see the guides for .NET, PHP or Ruby.
    • If you are building directly to our API, see the API reference.

Example of deviceIdentifier:

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

Device DNA™ · Mobile only integration

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

  1. Register card – Customer 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.

Note: Device DNA™ is not available for the Xamarin SDK.


Sandbox testing

Judopay offers a sandbox environment for you to easily test payments with your app and ensure your integration is correct before going live. Test all the payment types generating successful, declined and error results. Before you go live. Ensure that you are confident everything is working as expected.

Judopay releases updates to our sandbox environment regularly, we recommend continuous testing to ensure your integration is working with the latest updates.

Access test card details

To generate transactions, you can only use test cards. These are accessed via the dashboard, under ‘Tools’ and then selecting ‘Generating transactions’. If you are looking to use other card types for testing, please contact us and we will provide you with test card details.

Common test scenarios

Test your project with all the payment types required, i.e. Register a card and Repeat card payments.

Successful payments
Use the card details provided in the dashboard for generating a successful transaction. Make sure to capture and record the ‘receipt ID’ for this transaction.

If you intend to support repeat payments (one-click payments for example), you should capture the ‘card token’, ‘consumer token’ and the ‘consumer reference’. All three fields need to be provided in a repeat payment for it to be successful.

Note: Please ensure all transactions reaches your back-office.

Declined payments
This test scenario is for generating a declined payment status and applies to Card payments, Pre-authorizations and Repeat card payments. When testing for a ‘Payment declined’ result, you should process transactions with the following variables:

  • Incorrect CV2 (card security code) values
  • Incorrect/Invalid dates
  • Invalid card numbers
  • In repeat payments, use an incorrect match of card token and consumer reference

Payment errors
In case of an unexpected error occurring during a payment, i.e. if there is an upstream error processing a transaction, you need to ensure this is handled by your app/backend (depending on your integration).

One example of a test you can perform is to pass an invalid token and secret to see how your app handles the error.

Test security features

To protect your business and your customers against fraudulent transactions, test the security features included in your project.

Address Verification Service (AVS) (if used)
To check AVS, use the test card details provided on the dashboard. We recommend performing tests generating successful and declined payments:

  • Using the correct billing Postcode/Zip code
  • Using the incorrect billing Postcode/Zip code

3D Secure
If you want to test 3D Secure in the sandbox environment, please contact us and we will provide you with test card details to allow you to test if the 3D Secure web page is displayed in your app at the time of transaction. The sandbox environment displays a 3D Secure simulator page that allows you to simulate a success or decline 3DS result. You should check how your app responds to the different results.

Device DNA™
Ensure you have taken all the necessary steps to prevent fraudulent payments. Check that you have integrated all the fields in the API reference section. This applies to mobile and server integrations. For more information please see Device DNA™.

Web payments

If you are using web payments, we recommend to test:

  • Successful result
    Ensure that the payment process redirects the customer to the ‘Success URL’ (set in the dashboard).
  • Declined result
    Ensure that the payment process redirects the customer to the ‘Failure URL’ (set in the dashboard).
  • Cancelled transaction
    In the Web payments UI, the customer has the option to click ‘Cancel’. In this case we recommend that you return the customer to the URL they visited before the Web payment was initiated.

Terminology

Judopay API
Judopay’s core API for processing transactions.

Software Development Kit (SDK)
Judopay’s mobile SDKs for iOS · ObjC, iOS · SwiftAndroid and Xamarin enable you to accept payments easily in your app. Judopay’s server side SDKs for PHPRuby and .NET provide an easy to use interface for developers.

Dashboard
The dashboard is Judopay’s online management tool, where you can create your app(s), get your token and secret, and configure your applications (permissions, webhooks, web payments URLs, etc). You can also view transactions, request refunds and settle funds.

Sandbox environment
Judopay’s sandbox environment is accessed via the dashboard and is used for testing your app to ensure your integration is correct. For testing sandbox transactions, you would have to use the test card details (provided on the dashboard).

Live environment
Judopay’s live environment is accessed via the dashboard. You transact in this environment upon successful integration. For testing live transactions, you would have to use live card details (real debit/credit cards).

Judo ID
A unique ID (e.g. ‘123-456’ or ‘654321’) supplied by Judopay. This is specific to a merchant and/or location you wish to pay.

Token and secret
A unique string of alphanumeric characters that you use to access the Judopay API servers. You create the token and secret the dashboard and insert these into the headers of every request you send to Judopay. You need to use one set of tokens for the ‘Sandbox’ environment and a separate set of tokens for the ‘Live’ apps. 

Card token
A card token is a randomly generated string linked to the saved card in Judopay’s systems. It can be stored in your database without worrying about PCI compliance issues. This card token can only be used with the associated consumer token.

Consumer reference
The Consumer reference is used to help merchants to reconcile as well as prevent fraud from occurring through the system. 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. We recommend a GUID (Globally Unique Identifier) generated internally by your system. After a Consumer reference has been created, make sure it is an exact match (case sensitive) on subsequent transactions.

Payment reference
Your reference for a payment. This value should be unique in order to protect your customers against duplicated transactions.  With a server side integration and web payments, 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.

Payment metadata
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.

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

Block threshold
The JudoShield ‘Risk score’ determines if a transaction is Allowed, Blocked or sent to 3D Secure (learn more about 3DS). If the ‘Block threshold’ is reached, the transaction and/or user is flagged, preventing them from completing this transaction or any future transactions.

Device DNA™
Device DNA™ is an essential component of JudoShield. It enables Judopay to capture information about the mobile device to protect you from fraud in real-time. In order to protect your app from fraud you must setup Device DNA™. 

Device signals
Signals picked up from a device (i.e. mobile/cellular phone) that allows Judopay to power its fraud prevention product by recognizing the behaviour of that particular device.

Code obfuscation
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.