Important to Consider When Integrating your App

When to have Multiple JudoIds

You can have:

• One judoId

• Multiple judoIds

A judoId can be allocated for a route or location basis. Multiple judoIds can also be created to take into account a more granular set of transaction reporting, for example to separate online transactions, the location where transactions took place, or the most used payment method.

All judoId's can have different configurations enabled.

 

Permissions

You will receive your API credentials when setting up your account with Judopay. These credentials control the permissions enabled on your sandbox and live token and secret pair(s).

Each Token and Secret pair will have specific permissions configured. For more information, see Token and Secret App Permissions.

 

The following illustration provides a helpful overview on the permissions that need to be set up, in order for each step in the payment flow to be able to take place:

 

Possible Configuration Examples:

Depending on the payment methods, currencies and card schemes you want to accept, you can configure these specifically, (for example Visa, Mastercard, Apple Pay, Card, PayPal), or set to accept All.

Check your judoIds and tokens are configured and enabled as appropriate.

If you want to include AMEX, contact Customer Support to set this up. AMEX is not automatically added and requires a separate configuration.

• Payment Methods

• Transaction Medium (ECOM/MOTO)

• Currencies

• Card Schemes

• Transaction Types

• Block Payments from a Specific Region

 

Using our Transaction API

For more information, see How to use our Transaction API Reference Documentation.

 

Authentication Methods

For more information, see Authentication Methods.

 

Testing your Integration

Prior to Testing - Prerequisites

Make sure you have the following set up prior to testing:

• You are using sandbox tokens in the sandbox environment.

• You are using test cards in the sandbox environment.

• Your judoIds and tokens are configured and enabled as appropriate.

 

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

Test all your required payment types in the sandbox environment, using the Test Cards to test your integration is working correctly. This will give you confidence for when your integration goes live.

 

Sandbox Environment

Direct API Integration Scenarios (Card Payments):

• Payment flows including 3D Secure 2 Authentication

• Payments

• Refunds

• PreAuths

• Collections

• Voids

• SaveCard

• CheckCard

• RegisterCard

• Merchant Initiated Transactions

• GET a list or GET an individual transaction(s)

For more information see, Testing your Direct (API) Integration.

 

Web Payments Integration Scenarios (Card Payments):

• Payments

• PreAuths

• CheckCard

For more information see, Testing Web Payments - Card Payments.

 

Mobile SDK Integration Scenarios (Card Payments):

• Android

• iOS

For more information see, Testing your Mobile SDK Integration.

 

Web SDK Integration Scenarios (Card Payments):

• Payments

• PreAuths

• CheckCard

• Token Payments

• Token PreAuths

For more information see, Testing Web SDK - Card Payments.

 

Wallet Payment Scenarios (via direct API Integration):

• Apple Pay™

• Google Pay™

For more information see, Testing your Wallet Payment Integration.

 

Wallet Payment Scenarios (via Web SDK Integration):

• Apple Pay™

• Google Pay™

For more information see, Testing your Wallet Payment Integration.

 

Wallet Payment Scenarios (via Mobile SDK Integration):

• Apple Pay™

• Google Pay™

For more information see, Testing your Wallet Payment Integration.

 

Key Terms

Familiarise yourself with the key terms we use, to help you with your integration:

judoId

The judoId is a unique ID supplied by Judopay, which you add to the request body of each transaction request.

• String of numbers

• Maximum length 9 characters

• Format: 100100100

• Do not include spaces or dashes

 

API Credentials

You will receive your API credentials when setting up your account with Judopay. These credentials control the permissions enabled on your sandbox and live token and secret pair(s).

Each Token and Secret pair will have specific permissions configured.

For more information, see Token and Secret App Permissions.

 

3D Secure 2

The following 3D Secure 2 versions are supported:
- 3DS2.1
- 3DS2.2

 

3D Secure 2.0 aims to improve the security and consumer experience, including helping merchants achieve Strong Customer Authentication (SCA) compliance under PSD2.

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.

 

Make sure you have 3D Secure enabled API credentials. Contact ​Customer Support​​ to set this up.

In the 3D Secure 2 payment flow, the Issuer will make a decision on whether they have enough authentication data to proceed with the transaction, or if they require the cardholder to further authenticate the transaction with additional Strong Customer Authentication (SCA) checks.

 

To authenticate the transaction, merchants can verify the consumer's identity with the Issuer. To be compliant with SCA, 3D Secure 2 transactions have additional authentication and transaction information within the payment flow.

The deadline for PSD2 and SCA implementation for all the European Union countries members and UK merchants has now passed.
3D Secure 1 is no longer supported.

We have made it a simple implementation for you to upgrade to 3D Secure 2 within your payment flow. See Integrating 3D Secure 2 (EMV 3D Secure)

For more information, see 3D Secure.

 

Merchant-Initiated-Transactions

Merchant-Initiated-Transactions (MIT)s, for example:

• Subscription type payments

• Unscheduled transactions

  • tips

  • increase in taxi fares

For more information, see Merchant Initiated Transactions

 

MITs are also impacted by SCA. You need to tag your MIT/Recurring transactions correctly to ensure your transactions are not declined by your customers’ issuing bank.

 

Card Token Payments

Use the card token in the request body, instead of the card number. The card token is a randomly generated string linked to a card saved securely within the Judopay Card Vault.

You will not take on additional PCI scope, as the card token does not have any sensitive card information, so it can be stored in your database.

 

Alternative Payment Methods

Alternative Payment Methods refers to a range of payment methods beyond the traditional ways of paying with cards and cash.

Currently Judopay accepts the following alternative payment methods:

• Apple Pay™

• Google Pay™

• PayByLink

• iDEAL

• PayPal (BETA)

• Klarna (BETA

For more information, see Alternative Payment Methods.

 

Web Payments

A minimal integration is all that is required to enable you to take a payment.

Generate hosted payment page links using Judopay’s Transaction API and redirect the consumer back to your own website, using configured redirect URLs.

This helps minimise your PCI scope by providing consumers with a secure way to pay online via their browser, optimised for any device.

 

For more information, see Web Payments.

 

SDKs

Judopay’s SDKs enables merchants to easily integrate and customise a seamless consumer checkout experience, for Mobile, Web and Server integrations.

All of our SDKs come built-in with the following features:

• Secure Customer Authentication (SCA) compliance: 3D Secure.

• Fraud Prevention Tools

• Supports Alternative Payment Methods

• You will not take on additional PCI scope, as sensitive card information is submitted by consumers into fields hosted by Judopay, encrypted and transmitted on behalf of the merchant, meaning it does not touch the merchant’s server.

If you prefer to use your own UI for the consumer’s checkout journey, you can still easily integrate with Judopay using only a few lines of code to begin accepting payments.

For more information, see:

• Mobile

• Web SDK

• Server SDKs

 

Navigating the Judopay Portal

Access the Judopay Portal, to:

• Create your apps

• Configure your apps' permissions

• Access sandbox and live tokens and secrets

• Set up webhooks

• View transactions

• Process refunds

Create and configure your apps, access your tokens and secrets, view transactions, set up webhooks and process refunds, on the Judopay Portal.

When you sign in to the Judopay Portal, the side navigation has the following menu options:

 

Section	Options
	Account Section:   Overview: Overview of Account | Recent Live Transactions | Account Balance | Previous Transfers History: View Transactions in Sandbox and Live Environments | Search for Specific Transactions | View Filtered Transactions | Export Transactions to .csv Payments Dashboard: View Payment Summary for Last 24 Hours | View Total Transaction Value (Gross) for Past 30 Days | View Total Transaction Count for Past 30 Days  Declines Dashboard: View Declined Transactions by Month | View Declined Transactions Summary for Last 30 Days | View Declines by Acquirer Response Codes Pay By Link: View Existing PayByLink Payments | Create a new PayByLink Payment Balance: Detailed Account Balance View | Past Transfer Activity V-terminal: Virtual Terminal Settings: Provides the Judo ID | Transaction Fees | Funding Delay | Additional Account Details and Options | Transfer Details | Set Transfer Frequency for the Designated Account
	Developers Section:   Your Apps: Configure Your App |Access Tokens | Access Secrets Tools: Download our SDKs | Sandbox Test Card Details | API Transaction Logs PayPal:
	Help Section:   Portal Guide: Guide to Navigate the Portal Contact: Complete the Form to Judopay Customer Support

 

Creating your App

From the Judopay Portal:

Step	Description
	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.
	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.

 

Token and Secret App Permissions

To maximise your app’s security it is important to set permissions to allow your app to accept and process specific endpoints or payment types.

Each Token and Secret pair related to an app has its own unique permissions.

 

It is advised to enable the absolute minimum permissions required for your mobile app.

For example, if you only perform transactions from your backend; in your backend app enable the Make Payments permission.

The following app permissions are available:

• List All Transactions

• Make Payments

• Refund Payments

• Retrieve Web Payment

• Create Web Payment

• PreAuth Transactions

• Register Card Transactions

For Mobile apps, it is recommended not to make a transaction from the app, as the Token and Secret could become compromised.

Create a Register Card app and enable the Register Card Transactions permission, and use the server to make the transaction.

 

Edit Token and Secret App 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 edit the Sandbox Token and Secret app permissions in the Judopay Portal:

Step	Description
	From the side menu, select Your apps Select the app you wish to edit. For the purpose of this exercise, Document Testing App is selected.
	Select the environment to set permissions: Sandbox tokens Live tokens For the purpose of this exercise, Sandbox tokens is selected
	The token information is displayed. Native apps have the following default permissions: Make Payments PreAuth Transactions Register Card Transactions Click Edit
	The Permissions window appears. Select or deselect a permission. For the purpose of this exercise, List all Transactions is selected
	Click Save Permissions
	The added permission appears in the list. Test to validate the change has taken effect.

 

Viewing the Sandbox Token and Secret

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.

For the purpose of this exercise, view the Sandbox Token and Secret in the Judopay Portal.

From the Judopay Portal:

To view the Sandbox Token and Secret:

STEP	DESCRIPTION
	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.

 

Viewing the Live Token and Secret

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.

For the purpose of this exercise, view the Live Token and Secret in the Judopay Portal.

From the Judopay Portal:

To view the Live Token and Secret:

Step	Description
	From the side menu, select Your apps Select the app to view the Token and Secret credentials.
	Select Live tokens to see both the Token and Secret for the Sandbox Environment.
	The Live Token information is displayed. A Live Token and Secret will only be visible within the app once your account is activated. To activate your account, see Introduction.

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

 

Additional Token and Secret Settings

At the API Token / API Secret level, additional settings can be initiated:

• Enabling Webhooks

  • You can set webhooks to be enabled, see Enable Webhooks.

Contact customer support to set up the following features:

• Enabling WebPayments

• Enforcing AVS (Address Verification)

• Enforcing 3DS

• CV2 (Optional)

 

Webhooks

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

The benefit of using webhooks means you do not need to pull information from the Judopay API for every event.

Webhook Model

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

The benefit of using webhooks means you do not need to pull information from the Judopay Transaction API for every event.

Example Webhook Model

The transaction or event data is passed via a POST request to your notificationUrl using the content parameter.

The time-out default value is 15 seconds.

The example below shows the information the webhook message can contain:

 

It is recommended you create a script to retrieve the data from the content parameter in the receipt model.
The data can then be parsed and used as normal.

 

Enable Webhooks

To receive webhooks you are required to use TCP Port 443.

From the Judopay Portal:

Step	Description
	From the side menu, select Your apps Select the app you wish to edit. For the purpose of this exercise, Document Testing App is selected.
	Select Webhooks configuration
	Select the Webhooks for your required transaction type(s): Enable Webhooks Payment Enable Webhooks Collection Enable Webhooks PreAuth Enable Webhooks Refund Add your Webhooks URL
	Click Save Webhooks
	The Add authentication section appears. Click Add authentication
	Confirm and click Add authentication
	Your unique username and password for authentication will be displayed. The username and password will be combined with a colon separating them and will be encoded using Base64.
	Click Save Webhooks The selected Webhooks will now be authenticated using this method. Judopay will send this username and password along with every request.

Webhooks will not work until you add the authentication.

 

If you have any issues enabling webhooks, contact Customer Support and provide the notificationUrl.
This is the URL where you would like Judopay's Transaction API to POST the webhook message to.