NAV Navbar
ruby php java csharp objc swift

Introduction

Welcome

Accept simple and secure payments in your app or website with Judopay’s SDKs. Quickly capture your customer’s card details for immediate payments or save them securely for future payments.

Getting started is simple! Once you’ve signed up, you’ll receive access to your Judopay dashboard and the Sandbox environment.

In the area of finance technology there is a due diligence process to complete before you go live so please speak to a member of the team before doing any development work.

You can contact us at help@judopayments.com, by using our live chat service available from your dashboard or simply call us on 0203 503 0600 and select option 2 for support. Customer Support is available Monday to Friday 9am-6pm.

When you are ready just let us know, we can activate your account and carry out testing, then you can start processing payments!

Create your Sandbox Account

Click here to get access to your Judopay dashboard and the sanbox enviroment to begin integrating!

Overview

There are 4 methods to integrate with Judopay:

How tokenization works

Judopay will tokenize your customer’s credit/debit card information for you to use in future payments. Tokenization ensures that your customer’s card information is collected and stored in a secure PCI-DSS compliant manner, minimizing your PCI liability as no card information is stored on your backend. This frees up your time to focus on developing other areas of your app.

Tokens will be passed back to you in the form of a callback if you integrate using ‘Mobile and your server-side’ or ‘Web payments’. If you chose to integrate using ‘Mobile only’, the token will be stored directly on the customer’s device.

See Payments for more information on tokens and payment types. For more information on PCI, please see the PCI compliance guide provided by the PCI Security Standards Council.

Mobile and your server-side

Use our native SDKs which lets customer's save their card details in your mobile app and store the tokenized cards on your backend for future payments. There are 4 steps to this:

  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. Token payment– Perform future payments using the stored token.

Judopay’s customizable UI comes with built-in checks and security features, including data and address verification, real-time error detection and 3D Secure for frictionless card data capture. Our SDKs are also fully loaded with mobile-specific fraud prevention tools and allows for alternative payment methods such as Apple Pay and Android Pay.

For this method, Judopay provides server SDKs for all repeat payments directly from your backend. You can also use our webhooks to notify your backend when a transaction has taken place. If you do not use either of the languages below you can build directly to our API.

Judopay Additions

Judopay Additions is our new payments solution which allows you to embed a customisable iframe directly into your checkout page.

Once a user inputs their credit card data into the iframe, we provide you with a one-use token which can be used to carry out the payment from your back-end.

Please see the Additions section for more information.

Web payments intro

Integrate simple and secure card payments into your website or web app with web payments optimized for mobile screens. There are 6 steps to this:

  1. Web payment request – Call Judopay’s web payment services.
  2. Redirect response – Judopay will respond with your URL.
  3. Redirect to hosted payments page – You redirect your customer to the payment page.
  4. Complete payment – User enters in their card details.
  5. Complete response – Judopay responds with success or decline.
  6. Redirect to success or decline – Judopay redirects your customer to the outcome that is specified by you for success or failure.

If you are aiming to host web payments with an app, please note that redirects slow everything down. 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.

Mobile only

The ‘Mobile only’ solution is a new way to integrate that allows you to minimize your integration time and cost as the fraud protection and payments will be taken care of by Judopay. In this option, you can use Judopay’s customizable native SDKs to process all of your payments.

There are 5 steps to this:

  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 – Judopay’s SDK can perform all future payments using the token.
  5. Notifications – Judopay will update your system via a method that suits you, i.e webhooks. In this method, refunds can be done via the Judopay dashboard or via the token you will receive from Judopay. You are responsible for storing card tokens on the consumer’s device. See Secure your mobile app.

Help & Support

If you have questions about anything not covered in our documentation, need assistance integrating, or are unsure where to go from here, our developer support team is here to help.

Getting started

Environment management

All the examples in this document are using the sandbox environment. This environment allows you to process test transactions while developing your app. Check our testing sandbox environment guide for further detail.

When you are ready to go live, delete the ‘-sandbox’ from the URL and use your live token and secret.

Dashboard

The Judopay Portal dashboard is the place to go for creating/configuring your apps, accessing your token and secrets, viewing transactions and processing refunds, and more.

The list below details the pages which appear in the left navigation tab when you sign in to the portal.

Create an app

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

  1. If this is your first app, you will see the app creation page (skip to step 3). If you are creating an additional app, go to ‘Your apps’ and click on the ‘Add an app’ button.
  2. 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.
  3. Click the ‘Add app’ button. You will see the new app listed within the ‘Your apps’ section.

Access token and secret

Each app created is listed in the dashboard under the ‘Your apps’ section. Each app has a token and secret pair for Sandbox and Live. 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 TO DO). 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.

Important fields

Before starting transactions it is important to understand some of the key fields that are sent between your app and Judo when making payments. This section details a few of these fields and their requirements.

Judo ID

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.

The Judo ID is a string of numbers of 6-10 characters in length.

Your Consumer Reference

A Consumer Reference must be supplied in a payment request. It should be an identifier that allows you to 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.

Your Payment Reference

Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions.

Terminology

As well as the fields above, it is important to understand some of the key concepts in mobile/web payments with Judopay:

Judopay API Judopay’s core API for processing transactions.

Software Development Kit (SDK) Judopay’s Mobile SDKs (including iOS, Android, Xamarin) enable you to accept payments easily in your app. Judopay’s server side SDKs for PHP, Ruby 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).

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.

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.

Card types

The card types supported by Judo are each given an ID, these are listed in the look up table below:

ID Card Type
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

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.

Webhooks

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 choose not to pull information from the Judopay API for every event.

The events you can use webhooks for are:

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

Web payments method

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.

Next, please follow the web payments section for a technical guide on integrating Judo Web Payments with your website/webapp.

If you are aiming to host web payments with an app, please note that redirects slow everything down. 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.

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. It is advised to test all the payment types generating successful, declined and error results.

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:

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.

Securing 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:

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.

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

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.

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.

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.

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();

iOS

Example of iOS SSL pinning.

Set up Device DNA

In order to protect your app from fraud you must setup JudoShield. It enables Judopay to capture data from the transaction and device, which protects 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 setup 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:

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.

  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:

  1. Depending on your mobile app, follow the getting started guide for integrating Device DNA™ for iOS or Android.
  2. With the deviceIdentifier, key and value returned, send these values up to your API.
    • If you are using the .NET, PHP 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.
  3. 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.

Payments API

This payments section gives a high-level overview of the main operations involved with processing payments through Judopay. At the core of our payment processing platform is the Judopay API. You can use the API to process multiple payment functions and configure a checkout to suit your business needs.

Interact with Judopay using our Native SDKs for payments within a native app or Web payments within a mobile website or web app.

This overview covers the different payment functions that Judopay offers.

Register a card

register_card = Judopay::RegisterCard.new(
  :your_consumer_reference => '12345',
  :your_payment_reference => '67890',
  :card_number => '4976000000003436',
  :expiry_date => '12/20',
  :cv2 => '452',
)
$registerCard = $judopay->getModel('RegisterCard');
$registerCard->setAttributeValues(
    array(
        'judoId' => 'your_judo_id',
        'yourConsumerReference' => '12345',
        'yourPaymentReference' => '12345',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/15',
        'cv2' => 452
    )
);
Intent intent = new Intent(context, RegisterCardActivity.class);
intent.putExtra(Judo.JUDO_OPTIONS, new Judo.Builder()
        .setJudoId("your_judo_id")
                .setConsumerRef("yourConsumerRef")
                .build());

startActivityForResult(intent, REGISTER_CARD_REQUEST);

// In calling activity
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(requestCode == REGISTER_CARD_REQUEST) {
        switch (resultCode) {
            case JudoPay.RESULT_SUCCESS:
                Receipt receipt = data.getParcelableExtra(JudoPay.JUDO_RECEIPT);
                // save the receipt for performing future token payment
            }
    }
}

Card registration will tokenize a card into an encrypted string to process future payments.

The ‘Register card’ method conducts a pre-authorization configured to reserve a specific amount in the customer’s bank account. The pre-authorization can then be voided in order to not appear in the customer’s bank statement.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/registercard
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

RegisterCardModel Query Parameters

Param Type Description
cv2
Required
string CV2 from the credit card, also known as the card verification value (CVV) or security code. The 3 or 4 digit number on the back of a card
cardNumber
Required
string The unique number printed on a credit card, should be submitted without any whitespace or non-numeric characters
expiryDate string The expiry date of the card, should be submitted as MM/YY
startDate string For Maestro cards, the start date should be submitted as MM/YY
issueNumber int For Maestro cards, a number between 1 and 2 digits (from 0 to 99), located normally on the front of your card
cardAddress see table The address of a card holder
yourConsumerReference
Required
string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more
yourPaymentReference
Required
string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
judoId string 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. Read more
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.

CardAddress Query Parameters

Param Type Description
address1 string The first line of the card holder address
address2 string Any second line of the card holder address
town string The town of the card holder address
postCode string The postcode of the card holder address
countryCode int The optional country code (ISO 3166-1) for this address. UK is 826
line1 string First line of the card holder address
line2 string Second line of the card holder address
line3 string Third line of the card holder address
city string The city of the card holder address

Register Card Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
amountCollected decimal PreAuths will have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
device see table Specific device details for help in identifying a consumer
riskScore int
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

Device Response Fields

Param Type Description
identifier string

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string
merchantSuggestion string if risk statistics are enabled we're only going to suggest
merchantStatistics dictionary

Save card

save_card = Judopay::SaveCard.new(
  :your_consumer_reference => 'ххххххххххх',
  :card_number => '4976000000003436',
  :expiry_date => '12/20'
)
$saveCard = $judopay->getModel('SaveCard');
$saveCard->setAttributeValues(
    array(
        'judoId' => 'xxxxxxx',
        'yourConsumerReference' => 'xxxxxx',
        'yourPaymentReference' => 'xxxxxx',
        'cardNumber' => 'xxxxxxxxxxxxxxxxxxxxx',
        'expiryDate' => 'xx/xx'
    )
);

The save card operation is similar to Register card, in that card information is taken and mapped to a card token for use in future payments.

The key difference is Save Card does not perform a small pre-authorization on the card before saving, so unless it fails a luhn check, when saving a card, you may save a token for a card which when used, does not work for the payment.

Therefore, Save card can be useful for creating a card token for a card without pre-authorizing funds on a customers account. However, this card token is not tested until it is used (Register card will test the token as part of the pre-auth).

Http Header

POST https://gw1.judopay-sandbox.com/transactions/savecard
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

SaveCardModel Query Parameters

Param Type Description
cv2
Required
string CV2 from the credit card, also known as the card verification value (CVV) or security code. The 3 or 4 digit number on the back of a card
cardNumber
Required
string The unique number printed on a credit card, should be submitted without any whitespace or non-numeric characters
expiryDate
Required
string The expiry date of the card, should be submitted as MM/YY
startDate string For Maestro cards, the start date should be submitted as MM/YY
issueNumber int For Maestro cards, a number between 1 and 2 digits (from 0 to 99), located normally on the front of your card
cardAddress see table The address of a card holder
yourConsumerReference string A unique reference for you to identify your customer, it is advisable to use GUIDs, must be below 40 chars
judoId string 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.
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.

CardAddress Query Parameters

Param Type Description
address1 string The first line of the card holder address
address2 string Any second line of the card holder address
town string The town of the card holder address
postCode string The postcode of the card holder address
countryCode int The optional country code (ISO 3166-1) for this address. UK is 826
line1 string First line of the card holder address
line2 string Second line of the card holder address
line3 string Third line of the card holder address
city string The city of the card holder address

Save Card Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string

Check card

The check card operation is similar to Register card, in that card information is taken, mapped to a card token for use in future payments and the Issuing bank checks the card.

The key difference is Check Card does performs a zero amount pre-authorization on the card before saving, so this authorization can't be captured and doesn't hold any money on the consumer bank account.

Therefore, Check Card can be useful for creating a card token for a card without holding funds on a customers account. However, the issuing bank account won't check for funds.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/checkcard
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

RegisterCardModel Query Parameters

Param Type Description
cv2
Required
string CV2 from the credit card, also known as the card verification value (CVV) or security code. The 3 or 4 digit number on the back of a card
cardNumber
Required
string The unique number printed on a credit card, should be submitted without any whitespace or non-numeric characters
expiryDate string The expiry date of the card, should be submitted as MM/YY
startDate string For Maestro cards, the start date should be submitted as MM/YY
issueNumber int For Maestro cards, a number between 1 and 2 digits (from 0 to 99), located normally on the front of your card
cardAddress see table The address of a card holder
yourConsumerReference
Required
string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more
yourPaymentReference
Required
string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
judoId string 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. Read more
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.

CardAddress Query Parameters

Param Type Description
address1 string The first line of the card holder address
address2 string Any second line of the card holder address
town string The town of the card holder address
postCode string The postcode of the card holder address
countryCode int The optional country code (ISO 3166-1) for this address. UK is 826
line1 string First line of the card holder address
line2 string Second line of the card holder address
line3 string Third line of the card holder address
city string The city of the card holder address

Check Card Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string

Card payment

payment = Judopay::CardPayment.new(
  :judoId => '<JUDO_ID>',
  :your_consumer_reference => '<CONSUMER_REFERENCE>',
  :your_payment_reference => '<PAYMENT_REFERENCE>',
  :amount => 5.01,
  :currency => 'GBP',
  :card_number => '4976000000003436',
  :expiry_date => '12/20',
  :cv2 => '452',
  :card_address => {
    :line1 => '32 Edward Street',
    :town => 'Camborne',
    :postcode => 'TR14 8PA'
  }
)
$payment = $judopay->getModel('Payment');
$payment->setAttributeValues(
    array(
        'judoId' => 'your_judo_id',
        'yourConsumerReference' => '12345',
        'yourPaymentReference' => '12345',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/15',
        'cv2' => 452
    )
);
Intent intent = new Intent(this, PaymentActivity.class);
intent.putExtra(Judo.JUDO_OPTIONS, new Judo.Builder()
        .setJudoId("your_judo_id")
                .setAmount("1.00")
                .setCurrency(Currency.GBP)
                .setConsumerRef("<YOUR_REFERENCE>")
                .build());

startActivityForResult(intent, PAYMENT_REQUEST);

// In calling activity
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(requestCode == PAYMENT_REQUEST) {
        switch (resultCode) {
            case JudoPay.RESULT_SUCCESS:
                Receipt receipt = data.getParcelableExtra(JudoPay.JUDO_RECEIPT);
                // handle successful payment
            }
    }
}

A card payment covers the vast majority of retail transactions, such as in-store payments, settling a bill at a restaurant, or ordering goods remotely for delivery. A card payment has the most in common with traditional cash payments, with your customer’s card charged at the point of sale.

To process a card payment, your customer will be required to provide their full card details (16-digit card number, expiry date and CV2).

Http Header

POST https://gw1.judopay-sandbox.com/transactions/payments
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

CardPaymentModel Query Parameters

Param Type Description
cv2 string CV2 from the credit card, also known as the card verification value (CVV) or security code. The 3 or 4 digit number on the back of a card
cardNumber string The unique number printed on a credit card, should be submitted without any whitespace or non-numeric characters
expiryDate string The expiry date of the card, should be submitted as MM/YY
cardAddress see table The address of a card holder
startDate string For Maestro cards, the start date should be submitted as MM/YY
issueNumber int For Maestro cards, a number between 1 and 2 digits (from 0 to 99), located normally on the front of your card
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
yourPaymentMetaData jObject 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 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. Read more
amount decimal 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.
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
consumerLocation see table Consumer location represented as latitude and longitude co-ordinates
mobileNumber string If submitted must be the consumers valid UK mobile number (starting '+447' or '07')
emailAddress string A valid email address for the consumer
webPaymentReference string
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
userAgent string
deviceCategory string
acceptHeaders string
initialRecurringPayment boolean A true value indicates this is an initial payment for a recurring payment
recurringPayment boolean A true value indicates this is a recurring payment

CardAddress Query Parameters

Param Type Description
address1 string The first line of the card holder address
address2 string Any second line of the card holder address
town string The town of the card holder address
postCode string The postcode of the card holder address
countryCode int The optional country code (ISO 3166-1) for this address. UK is 826
line1 string First line of the card holder address
line2 string Second line of the card holder address
line3 string Third line of the card holder address
city string The city of the card holder address

ConsumerLocation Query Parameters

Param Type Description
latitude decimal
longitude decimal

Payment Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string

Payment Requires 3DS Response

PaymentRequiresThreeDSecureModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
result string
message string A message detailing the result
acsUrl string
md string
paReq string

Token payment

token_payment = Judopay::TokenPayment.new(
  :your_consumer_reference => 'xxxxxxxx',
  :your_payment_reference => 'xxxxxxxx',
  :amount => 5.01,
  :currency => 'GBP',
  :consumer_token => response_register_card.consumer.consumer_token,
  :card_token => response_register_card.card_details.card_token,
  :cv2 => '452'
)
$tokenPayment = $judopay->getModel('TokenPayment');
$tokenPayment->setAttributeValues(
    array(
        'judoId' => 'your_judo_id',
        'yourConsumerReference' => 'xxxxxxxx',
        'yourPaymentReference' => 'xxxxxxxx',
        'amount' => 10.00,
        'currency' => 'GBP',
        'consumerToken' => $responseRegisterCard['consumer']['consumerToken'],
        'cardToken' => $responseRegisterCard['cardDetails']['cardToken'],
        'cv2' => 452
    )
);
Intent intent = new Intent(this, PaymentActivity.class);
intent.putExtra(Judo.JUDO_OPTIONS, new Judo.Builder()
        .setJudoId("your_judo_id")
                .setAmount("1.00")
                .setCurrency(Currency.GBP)
                .setConsumerRef(receipt.getConsumer().getYourConsumerReference())
                .setCardToken(receipt.getCardDetails())
                .build());

startActivityForResult(intent, TOKEN_PAYMENT_REQUEST);

// In calling activity
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(requestCode == TOKEN_PAYMENT_REQUEST) {
        switch (resultCode) {
            case JudoPay.RESULT_SUCCESS:
                Receipt receipt = data.getParcelableExtra(JudoPay.JUDO_RECEIPT);
                // handle successful payment
            }
    }
}

Once your customer has processed their first successful payment, there’s no reason they should have to enter their details again when making subsequent payments to your business. Instead you can reduce the amount of data entry for returning customers by storing their data to process future payments.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/payments
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

TokenPaymentModel Query Parameters

Param Type Description
cv2 string CV2 from the credit card, also known as the card verification value (CVV) or security code. The 3 or 4 digit number on the back of a card
cardToken
Required
string The card token for a previously registered card.
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
yourPaymentMetaData jObject 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 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. Read more
amount decimal 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.
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
consumerLocation see table Consumer location represented as latitude and longitude co-ordinates
mobileNumber string If submitted must be the consumers valid UK mobile number (starting '+447' or '07')
emailAddress string A valid email address for the consumer
webPaymentReference string
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
userAgent string
deviceCategory string
acceptHeaders string
initialRecurringPayment boolean A true value indicates this is an initial payment for a recurring payment
recurringPayment boolean A true value indicates this is a recurring payment

ConsumerLocation Query Parameters

Param Type Description
latitude decimal
longitude decimal

Token Payment Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string

Token Payment Requires 3DS Response

PaymentRequiresThreeDSecureModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
result string
message string A message detailing the result
acsUrl string
md string
paReq string

CV2 confirmation

After a payment has been processed successfully, Judopay provides you with a card token and a consumer token. These tokens can be stored and used with the original Consumer Reference to process future payments on behalf of that customer. This means that by processing a token payment, returning customers will only need to enter their CV2 to complete the transaction.

One-click payments

We also offer one-click payments, whereby your customer will not be required to enter any card details for repeat payments. This situation is very useful, for example, when you want to set up recurring payments for subscriptions or top-ups on behalf of the customer. This is a custom feature, so if it’s one of your requirements please let us know.

Preauth

preauth = Judopay::CardPreauth.new(
  :your_consumer_reference => 'xxxxxxxx',
  :your_payment_reference => 'xxxxxxxx',
  :amount => 5.01,
  :card_number => '4976000000003436',
  :expiry_date => '12/20',
  :cv2 => '452',
  :currency => 'GBP',
  :card_address => {
    :line1 => '32 Edward Street',
    :town => 'Camborne',
    :postcode => 'TR14 8PA'
  },
  :consumer_location => {
    :latitude => 51.5033630,
    :longitude => -0.1276250
  }
)
$preauth = $judopay->getModel('Preauth');
$preauth->setAttributeValues(
    array(
        'judoId' => 'your_judo_id',
        'yourConsumerReference' => '12345',
        'yourPaymentReference' => '12345',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/15',
        'cv2' => 452
    )
);
Intent intent = new Intent(this, PreAuthActivity.class);
intent.putExtra(Judo.JUDO_OPTIONS, new Judo.Builder()
        .setJudoId("your_judo_id")
                .setAmount("1.00")
                .setCurrency(Currency.GBP)
                .setConsumerRef("<YOUR_REFERENCE>")
                .build());

startActivityForResult(intent, PRE_AUTH_REQUEST);

// In calling activity
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(requestCode == PRE_AUTH_REQUEST) {
        switch (resultCode) {
            case JudoPay.RESULT_SUCCESS:
                Receipt receipt = data.getParcelableExtra(JudoPay.JUDO_RECEIPT);
                // handle successful pre-auth
            }
    }
}

A business may choose to reserve (pre-authorize) funds on a card and postpone completing the payment until the goods have been delivered, or the service has been fulfilled.

For example, a taxi app might reserve funds at the start of a journey and collect them only after the journey is complete. You can use a pre-authorization to perform this ‘reserve and collection’ of funds.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/savecard
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

PaymentModel Query Parameters

Param Type Description
yourConsumerReference
Required
string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more
yourPaymentReference
Required
string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
yourPaymentMetaData jObject 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
Required
string 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. Read more
amount
Required
decimal 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.
currency
Required
string This property identifies the currency of this transaction. This can be any ISO 4217 alphabetic currency code such as GBP, USD or EUR
consumerLocation see table Consumer location represented as latitude and longitude co-ordinates
mobileNumber string If submitted must be the consumers valid UK mobile number (starting '+447' or '07')
emailAddress string A valid email address for the consumer
webPaymentReference string
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
userAgent string The Client's browser useragent for 3D secure
deviceCategory string The Client's browser DeviceCategory for 3D secure
acceptHeaders string The Client's browser DeviceCategory for 3D secure
initialRecurringPayment boolean Is this transaction the first transaction of a series (i.e. Continious authority has been granted to the merchant by the card holder). Mastercard requires that when dealing with continious authority payments we identify the transaction where the card holder gave permission for repeat charges.
recurringPayment boolean Is this transaction one of a series being processed using a continious authority agreement Mastercard requires that when dealing with continious authority payments we identify the transaction where the card holder gave permission for repeat charges.

ConsumerLocation Query Parameters

Param Type Description
latitude decimal
longitude decimal

Preauth Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string

Token Preauth

token_preauth = Judopay::TokenPreauth.new(
  :your_consumer_reference => 'xxxxxxxxx',
  :your_payment_reference => 'xxxxxxxxx',
  :amount => 5.01,
  :currency => 'GBP',
  :consumer_token => response_register_card.consumer.consumer_token,
  :card_token => response_register_card.card_details.card_token,
  :cv2 => '452'
)
$tokenPreauth = $judopay->getModel('TokenPreauth');
$tokenPreauth->setAttributeValues(
    array(
        'judoId' => 'your_judo_id',
        'yourConsumerReference' => 'xxxxxxxx',
        'yourPaymentReference' => 'xxxxxxxx',
        'amount' => 10.00,
        'currency' => 'GBP',
        'consumerToken' => $responseRegisterCard['consumer']['consumerToken'],
        'cardToken' => $responseRegisterCard['cardDetails']['cardToken'],
        'cv2' => xxx
    )
);
Intent intent = new Intent(this, PreAuthActivity.class);
intent.putExtra(Judo.JUDO_OPTIONS, new Judo.Builder()
        .setJudoId("your_judo_id")
                .setAmount("1.00")
                .setCurrency(Currency.GBP)
                .setConsumerRef(receipt.getConsumer().getYourConsumerReference())
                .setCardToken(receipt.getCardDetails())
                .build());

startActivityForResult(intent, TOKEN_PREAUTH_REQUEST);

// In calling activity
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(requestCode == TOKEN_PREAUTH_REQUEST) {
        switch (resultCode) {
            case JudoPay.RESULT_SUCCESS:
                Receipt receipt = data.getParcelableExtra(JudoPay.JUDO_RECEIPT);
                // handle successful pre-auth
            }
    }
}

You can also use a created card token to pre-authorise a payment, meaning you can make repeat pre-auths in the same way you can make repeat card payments without your customers having to re-enter their details.

Token preauths can then be collected in exactly the same way as a regular preauth.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/preauths
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

TokenPaymentModel Query Parameters

Param Type Description
cv2 string CV2 from the credit card, also known as the card verification value (CVV) or security code. The 3 or 4 digit number on the back of a card
cardToken
Required
string The card token for a previously registered card.
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
yourPaymentMetaData jObject 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 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. Read more
amount decimal 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.
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
consumerLocation see table Consumer location represented as latitude and longitude co-ordinates
mobileNumber string If submitted must be the consumers valid UK mobile number (starting '+447' or '07')
emailAddress string A valid email address for the consumer
webPaymentReference string
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
userAgent string
deviceCategory string
acceptHeaders string
initialRecurringPayment boolean A true value indicates this is an initial payment for a recurring payment
recurringPayment boolean A true value indicates this is a recurring payment

ConsumerLocation Query Parameters

Param Type Description
latitude decimal
longitude decimal

Token Preauth Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
risks see table
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Risks Response Fields

Param Type Description
postCodeCheck string

Collection

collection = Judopay::Collection.new(
  :receipt_id => result_preauth.receipt_id,
  :your_payment_reference => 'xxxxxx',
  :amount => 10.00
)
$collection = $judopay->getModel('Collection');
$collection->setAttributeValues(
    array(
        'receiptId' => $responsePreauth['receiptId'],
        'yourPaymentReference' => 'xxxxxx',
        'amount' => 10.00,
    )
);
CollectionRequest collectionRequest = new CollectionRequest(receiptId, amount);

JudoApiService apiService = Judo.getApiService(context);

apiService.collection(collectionRequest)
        .observeOn(AndroidSchedulers.mainThread())
        .subscribeOn(Schedulers.newThread())
        .subscribe(new Action1<Receipt>() {
            @Override
            public void call(Receipt receipt) {
                if(receipt.isSuccess()) {
                    // handle result
                }
            }
        });

Once a payment has been preauthed, we can then perform a collection operation to actually transfer the reserved funds.

In the taxi scenario from above, when the taxi arrives at its destination, you can update your system to send a request to collect the funds you’ve previously reserved.

For your customer at the checkout, there is no difference or extra work required to process a payment of this kind – it’s all carried out in the back-end. However, you can choose to let your customer know when they can expect their card to be charged with a simple message, such as: ‘You have not yet been charged for this item. We won’t debit any funds from your payment card until your journey is complete.’

Http Header

POST https://gw1.judopay-sandbox.com/transactions/collections
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

CollectionModel Query Parameters

Param Type Description
receiptId
Required
string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
judoId string 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. Read more
amount
Required
decimal 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.
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 jObject 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
yourPaymentReference
Required
string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs

Collection Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Void

void = Judopay::Void.new(
  :receipt_id => result_preauth.receipt_id,
  :amount => 5.01
)
$void = $judopay->getModel('VoidTransaction');
$void->setAttributeValues(
    array(
        'judoId' => 'xxxxxxxxx',
        'receiptId' => $responsePreauth['receiptId'],
        'amount' => 1000.00
    )
);
VoidRequest voidRequest = new VoidRequest(receiptId, amount);

JudoApiService apiService = Judo.getApiService(context);

apiService.voidPreAuth(voidRequest)
        .observeOn(AndroidSchedulers.mainThread())
        .subscribeOn(Schedulers.newThread())
        .subscribe(new Action1<Receipt>() {
            @Override
            public void call(Receipt receipt) {
                if(receipt.isSuccess()) {
                    // handle result
                }
            }
        });

If a transaction has been authorized by the card-holder bank, but the funds have yet to be settled, the merchant has the ability to cancel the transaction by voiding it.

PreAuths can also be beneficial if the customer’s purchase is at all contingent upon variables beyond your business’s control, such as availability of raw materials. With a pre-authorization you do not actually charge the card, which means you do not have to worry about processing a refund if the details of the order change.

If your business is not going to charge the customer, you will be able to void the pre-authorization.

You can also use a void when your intention is to obtain a card token by performing a pre-authorization, but you don’t want to incur actual charges against the cardholder’s account. We recommend to perform a card registration for obtaining tokens.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/voids
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

VoidModel Query Parameters

Param Type Description
receiptId
Required
string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
judoId string 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. Read more
amount
Required
decimal 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.
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 jObject 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
yourPaymentReference
Required
string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs

Void Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

Refund

refund = Judopay::Refund.new(
  :receipt_id => result_payment.receipt_id,
  :your_payment_reference => 'xxxxxxxx',
  :amount => 5.01
)
$refund = $judopay->getModel('Refund');
$refund->setAttributeValues(
    array(
        'receiptId' => $responsePayment['receiptId'],
        'yourPaymentReference' => 'xxxxxx',
        'amount' => 10.00,
    )
);
RefundRequest refundRequest = new RefundRequest(receiptId, amount);

JudoApiService apiService = judo.getApiService(context);

apiService.refund(refundRequest)
        .observeOn(AndroidSchedulers.mainThread())
        .subscribeOn(Schedulers.newThread())
        .subscribe(new Action1<Receipt>() {
            @Override
            public void call(Receipt receipt) {
                if(receipt.isSuccess()) {
                    // handle result
                }
            }
        });

If the details of one of your sales change, you might need to process a refund to return those funds to the customer.

Depending on the specifics of your situation, you may need to process a full or a partial refund.

Full refund returns the total of the original transaction back to the card holder. This is often employed in instances where the original agreement between buyer and seller has been rendered void and so no charges can be justifiably applied.

Partial refund returns a specified amount of the original transaction back to the customer. This can be used in scenarios where a customer has been overcharged or where part of an order can’t be satisfied by the business.

Http Header

POST https://gw1.judopay-sandbox.com/transactions/refunds
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

RefundModel Query Parameters

Param Type Description
receiptId
Required
string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
judoId string 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. Read more
amount
Required
decimal 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.
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 jObject 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
clientDetails jObject This is a set of fraud signals sent by the mobile SDKs
yourPaymentReference
Required
string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more

Refund Response

PaymentReceiptModel Response Fields

Param Type Description
receiptId string Our reference for this transaction. Keep track of this as it's needed to process refunds or collections later
yourPaymentReference string Your reference for this payment. This value should be unique in order to protect your customers against duplicated transactions. With a server side integration, if a payment reference is not supplied, the transactions will not be processed. Read more
type string Payment, Refund, PreAuth, or Collection
createdAt date An ISO8601 formatted date and time (including time zone offset)
result string
message string A message detailing the result
judoId long 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. Read more
merchantName string The trading name of the Merchant to whom payment has been made
appearsOnStatementAs string How the Merchant will appear on the Consumers statement
originalAmount decimal Refunds and PreAuths will not have this value
netAmount decimal This will show the remaining balance of the transaction after refunds. You cannot refund more than the original payment
amount decimal 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.
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
cardDetails see table Information about the card used in this transaction
consumer see table Details of the Consumer for use in repeat payments
yourPaymentMetaData jObject 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
threeDSecure see table If the payment requested 3d secure, we need to include the result of that authentication process
recurring boolean Informs if the payment was handled as recurring transaction Should not return if false

CardDetails Response Fields

Param Type Description
cardLastfour string Last four digits of the credit card number used for the transaction
endDate string Card's expiry date in MMYY
cardToken string Can be used to charge future payments against this card
cardType optional An integer code representing the card type. See card types for a list of card types
startDate string For Maestro cards, the start date should be submitted as MM/YY
cardScheme string
cardFunding string
cardCategory string
cardCountry string
bank string

Consumer Response Fields

Param Type Description
consumerToken string Our unique reference for this Consumer. Used in conjunction with the card token in repeat transactions
yourConsumerReference string A unique reference for you to anonymously identify your customer, it is advisable to use GUIDs, must be below 40 chars. Read more

ThreeDSecure Response Fields

Param Type Description
attempted boolean Did the consumer attempt to authenticate through 3d secure
result string what was the outcome of their authentication

3D Secure

Initiate the card payment

The developer initiates a 3DS payment with the normal payment request. For example:

{
    "yourConsumerReference": "wptestconsumer-9989",
    "yourPaymentReference": "payment12123421",
    "yourPaymentMetaData" : { "test":"data"},
    "judoId": "1009xxx",
    "amount": 1.01,
    "cardNumber": "497635xxxxxx6891",
    "expiryDate": "12/15",
    "startDate": "01/07",
    "cv2": "341",
    "currency" : "GBP",
    "cardAddress": {
        "line1": "",
        "line2": "xx",
        "line3": "",
        "town": "xx",
        "postCode": "TR14 8PA"
       },
   "consumerLocation": {
          "latitude": 51.5214541344954,
          "longitude": -0.203098409696038
        }
}

Response from Judo for 3D secure transaction 

Judo will return a json response with the "result" property set to "Requires 3D Secure". This response will include the "acsUrl", "md", "paReq" parameters you need to start the 3DS process.

3DSecureResponse

{
    "receiptId": "2888xx",
    "result": "Requires 3D Secure",
    "message": "Issuer authentication required",
    "acsUrl": "https://testURL";,
    "md": "15060910321695410xxxx",
    "paReq": "eJxVUttum0AQfa/Uf0A8O95dbgY03sgNikpV28h1PoAu0xjHLGSBYOfru2tD0ko87DnDXM6ZgftzdbLeULVlLZc2m1 xxxx...."
}

If judoShield is enabled the risk score for the transactions must exceed the 3D secure threshold before the Judopay API will attempt 3DS authentication.

Merchant dispatches the customer to the ACS server by POST request

At this stage some kind of webview or browser needs to be opened to show the customer the ACS page so that he can authenticate with his/her issuing bank. This web view needs to do a POST request to the acsUrl passing the following parameters:

Field Description
PaReq The "Payment authorisation request" describes the payment being authorised by 3DS
TermUrl The termination url, this is the location the ACS server will return the customer to in the event of either success or failure of the 3ds authorisation. For judoResponsive this is automatically set to our domain (https://pay.judopay.com), for in-app purchases this is set to a protocol handler (iOS and Android Docs)
MD An encrypted blob of information Judopay needs to resume the transaction

The 3DS field names are case-sensitive. Merchants must send the field names exactly like this: PaReq and MD

Consumer user journeys on the ACS server

The exact user journey the customer experiences will depend on a number of factors:

In all of these cases the customer will be returned to the TermUrl with a "PaRes" value identifying the outcome. If the customer closes their browser window there is no way to identify their actions. These transactions will remain as "open" 3D secure transactions awaiting 3ds authorisation.

Response from ACS URL

After completing 3D secure it will return back to TermUrl which should have PaRes and MD as form parameters

Send 3D secure complete to Judo

Use PaRes and Md to complete the 3D transaction with Judo by calling the Complete3DSecure API method, which sends a PUT request to 

https://gw1.judopay.com/transactions/{receiptId}

where receiptId is original receiptId from judo (step (3)). The body of this request looks like:

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

Judo will respond with a success/failure receipt

The Judopay 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 3DS process was not successfully completed.
Error There was a problem processing the PUT request, please confirm your forwarding the complete PaRes and MD values without modification.

List transactions

If you want to retrieve a record of previous transactions, you can call this endpoint.

GET a number of the Judopay API resources support paging and sorting. The paging for these resources is controlled using the following query-string parameters:

Http Header

GET https://gw1.judopay-sandbox.com/transactions
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password). URL Parameter | Description -|- pageSize | The number of records to display per-page (default 10) offset | The start point in the sorted list of records from which the results set will start. For example, "?pageSize=10&offset=20" will return the second page of results (default 0) sort | Determines how Judopay sorts the list. The list can be displayed as time-descending and time-ascending (default time-descending)

Paging is most useful on the transaction resources, where you can get a list of the last 15 transactions processed:

GET /transactions?pageSize=15&offset=0&sort=time-descending

Or the first 5 payments you processed:

GET /transactions/payments?pageSize=5&offset=0&sort=time-ascending

Get individual transaction

You can retrieve a single transaction by adding a receipt Id to the transactions endpoint.

Http Header

GET https://gw1.judopay-sandbox.com/transactions/{receiptId}
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

Authentication

In online and mobile payments, security is a number one concern. Authentication and verification of the identity of the cardholder is important for preventing fradulent transactions and refunds.

Judo supports the three primary methods of cardholder authentication in use today, including 3DS, CV2 and AVS, all are described below.

3D Secure

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

3DS is also known as Verified by Visa (VBV) and MasterCard Secure Code (MSC). Typical implementations of 3DS allow customers to create a password that is associated with their card.

A transaction using VBV or MSC redirects the customer to the authorization website of the card’s issuing bank. On this website, the customer is expected to provide the requested characters from their password in order to authorize the payment. Since the password is not stored on the card it reduces the risk of card fraud owing to a stolen card or card details.

CV2 confirmation

CV2, known as the card verification code (also called card security code), is the 3-4 digit security number placed at the back of the card, it is often used to authenticate a payee physically owns the card.

After a payment has been processed successfully, Judopay provides you with a card token and a consumer token. These tokens can be stored and used with the original Consumer Reference to process future payments on behalf of that customer. This means that by processing a token payment, returning customers will only need to enter their CV2 to complete the transaction.

Address verification

Address Verification System (AVS) is another fraud prevention scheme. It uses information provided by your customer to verify the details of the card used in the transaction. It is used to help verify details in cardholder not present transactions, such as online and mobile.

AVS performs a cross-reference check between the billing address of the payment card and the billing address provided by the customer. If the check is successful then the transaction will be processed, otherwise the charge will not be authorized.

AVS performs the cross-reference check using the numerical values contained in the address information.

Mobile SDKs

This section contains step by step tutorials for integrating with Judo using our mobile SDKs. Each guide will cover the basics from the initial development steps, additional configuration options, all the way through to going live and testing your app.

Google Pay

All code samples in this section are in Java, please switch to the java tab on the right.

How it works

Google Pay is the new mobile payment solution from Google which is replacing Android Pay.

With Google Pay integration in your app, your customers can check-out in an extremely fast and seamless way, using payment cards they have saved to their Google Wallet (on Android devices).

User Requirements

Google Pay works with credit or debit cards from participating card-issuing banks on Android devices running versions 5.0+ (Lollipop).

Customers can use devices that are not NFC-enabled to make Google Pay purchases in merchant mobile apps.

Judo Android SDK

The next sections assume you have Judo's Android SDK as a dependency in your Android application. For adding the SDK into your app's dependencies using gradle, please see the Android SDK section.

Much of the sample code in the next section is implemented in the same way as the Google Pay sample application project on git. It's worth checking out this sample as many of the files can be reused, such as the Constants and PaymentUtil java classes.

Configuring Wallet

With Google Pay there are two environments, Sandbox and Production. This is reflected by the WalletConstants enum in the android wallet package.

You must specify your payments environment to be one of these values.

public static final int PAYMENTS_ENVIRONMENT = WalletConstants.ENVIRONMENT_PRODUCTION;




Google Pay supports both tokenized and non-tokenized cards. With tokenized payments, Google generates a token which represents a card, and only this token is sent when making a payment, your customers card number does not leave Google.

For security reasons, Judo only currently supports tokenized cards. Therefore you must configure your application to only support the tokenized card method. This means that any invalid cards will not appear as a payment option when your user tries to pay with your application.

public static final List<Integer> SUPPORTED_METHODS = Arrays.asList(
        // PAYMENT_METHOD_TOKENIZED_CARD refers to EMV tokenized credentials stored in the
        // Google Pay app, assuming it's installed.
        WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD
);






You must also set gateway name to "judopay".

public static final String GATEWAY_TOKENIZATION_NAME = "judopay";



When creating a new PaymentsClient (another Android class), you need to initialise it with the PAYMENTS_ENVIRONMENT set earlier, and also the activity launching your payment.

public static PaymentsClient createPaymentsClient(Activity activity) {
    Wallet.WalletOptions walletOptions = new Wallet.WalletOptions.Builder()
            .setEnvironment(Constants.PAYMENTS_ENVIRONMENT)
            .build();
    return Wallet.getPaymentsClient(activity, walletOptions);
}







Set the tokenization parameters with your merchant ID (Judo ID).

public static final List<Pair<String, String>> GATEWAY_TOKENIZATION_PARAMETERS = Arrays.asList(
    Pair.create("gatewayMerchantId", "{YOUR_JUDO_ID}")
);





You must also specify the card networks you want to support, and allowed shipping countries (might vary depending on your application/product).

// The allowed networks to be requested from the API. If the user has cards from networks not
// specified here in their account, these will not be offered for them to choose in the popup.
public static final List<Integer> SUPPORTED_NETWORKS = Arrays.asList(
        WalletConstants.CARD_NETWORK_AMEX,
        WalletConstants.CARD_NETWORK_DISCOVER,
        WalletConstants.CARD_NETWORK_VISA,
        WalletConstants.CARD_NETWORK_MASTERCARD
);

// Supported countries for shipping (use ISO 3166-1 alpha-2 country codes).
// Relevant only when requesting a shipping address.
public static final List<String> SHIPPING_SUPPORTED_COUNTRIES = Arrays.asList(
        "US",
        "GB"
);


















Generating a Google Pay payment

In your checkout activity, find the view/button which will trigger the Google Pay payment and add the request payment listener. The Google Pay sample application project has a sample view layout for a Google Pay button you can use (googlepay_button.xml) which follows the Google Pay style conventions.

// Arbitrarily-picked result code.
private static final int LOAD_PAYMENT_DATA_REQUEST_CODE = 991;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_checkout);


    mGooglePayButton = findViewById(R.id.googlepay_button);
    mGooglePayStatusText = findViewById(R.id.googlepay_status);

    mGooglePayButton.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View view) {
            requestPayment(view);
        }
    });

    // It's recommended to create the PaymentsClient object inside of the onCreate method.
    mPaymentsClient = PaymentsUtil.createPaymentsClient(this);
    checkIsReadyToPay();
}

// This method is called when the Pay with Google button is clicked.
public void requestPayment(View view) {
    // Disables the button to prevent multiple clicks.
    mGooglePayButton.setClickable(false);

    // The price provided to the API should include taxes and shipping.
    // This price is not displayed to the user.
    String price = PaymentsUtil.microsToString(YOUR_ITEM_PRICE);

    TransactionInfo transaction = PaymentsUtil.createTransaction(price);
    PaymentDataRequest request = PaymentsUtil.createPaymentDataRequest(transaction);
    Task<PaymentData> futurePaymentData = mPaymentsClient.loadPaymentData(request);

    // Since loadPaymentData may show the UI asking the user to select a payment method, we use
    // AutoResolveHelper to wait for the user interacting with it. Once completed,
    // onActivityResult will be called with the result.
    AutoResolveHelper.resolveTask(futurePaymentData, this, LOAD_PAYMENT_DATA_REQUEST_CODE);
}

private void checkIsReadyToPay() {
    // The call to isReadyToPay is asynchronous and returns a Task. We need to provide an
    // OnCompleteListener to be triggered when the result of the call is known.
    PaymentsUtil.isReadyToPay(mPaymentsClient).addOnCompleteListener(
            new OnCompleteListener<Boolean>() {
                public void onComplete(Task<Boolean> task) {
                    try {
                        boolean result = task.getResult(ApiException.class);
                        setGooglePayAvailable(result);
                    } catch (ApiException exception) {
                        // Process error
                        Log.w("isReadyToPay failed", exception);
                    }
                }
            });
}

private void setGooglePayAvailable(boolean available) {
    // If isReadyToPay returned true, show the button and hide the "checking" text. Otherwise,
    // notify the user that Pay with Google is not available.
    // Please adjust to fit in with your current user flow. You are not required to explicitly
    // let the user know if isReadyToPay returns false.
    if (available) {
        mGooglePayStatusText.setVisibility(View.GONE);
        mGooglePayButton.setVisibility(View.VISIBLE);
    } else {
        mGooglePayStatusText.setText(R.string.googlepay_status_unavailable);
    }
}
































































Create the PaymentDataRequest, passing in the gateway name and parameters set earlier, ensure to set the tokenization type as the WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY type:

public static PaymentDataRequest createPaymentDataRequest(TransactionInfo transactionInfo) {
    PaymentMethodTokenizationParameters.Builder paramsBuilder =
            PaymentMethodTokenizationParameters.newBuilder()
                    .setPaymentMethodTokenizationType(
                            WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
                    .addParameter("gateway", Constants.GATEWAY_TOKENIZATION_NAME);
    for (Pair<String, String> param : Constants.GATEWAY_TOKENIZATION_PARAMETERS) {
        paramsBuilder.addParameter(param.first, param.second);
    }

    return createPaymentDataRequest(transactionInfo, paramsBuilder.build());
}

private static PaymentDataRequest createPaymentDataRequest(TransactionInfo transactionInfo, PaymentMethodTokenizationParameters params) {
    PaymentDataRequest request =
            PaymentDataRequest.newBuilder()
                    .setPhoneNumberRequired(false)
                    .setEmailRequired(true)
                    .setShippingAddressRequired(true)

                    // Omitting ShippingAddressRequirements all together means all countries are
                    // supported.
                    .setShippingAddressRequirements(
                            ShippingAddressRequirements.newBuilder()
                                    .addAllowedCountryCodes(Constants.SHIPPING_SUPPORTED_COUNTRIES)
                                    .build())

                    .setTransactionInfo(transactionInfo)
                    .addAllowedPaymentMethods(Constants.SUPPORTED_METHODS)
                    .setCardRequirements(
                            CardRequirements.newBuilder()
                                    .addAllowedCardNetworks(Constants.SUPPORTED_NETWORKS)
                                    .setAllowPrepaidCards(true)
                                    .setBillingAddressRequired(true)

                                    // Omitting this parameter will result in the API returning
                                    // only a "minimal" billing address (post code only).
                                    .setBillingAddressFormat(WalletConstants.BILLING_ADDRESS_FORMAT_FULL)
                                    .build())
                    .setPaymentMethodTokenizationParameters(params)

                    // If the UI is not required, a returning user will not be asked to select
                    // a card. Instead, the card they previously used will be returned
                    // automatically (if still available).
                    // Prior whitelisting is required to use this feature.
                    .setUiRequired(true)
                    .build();

    return request;
}


















































Handle a successful payment

Catch the payment result in your checkout activity:

public void onActivityResult(int requestCode, int resultCode, Intent data) {
    switch (requestCode) {
        case LOAD_PAYMENT_DATA_REQUEST_CODE:
            switch (resultCode) {
                case Activity.RESULT_OK:
                    PaymentData paymentData = PaymentData.getFromIntent(data);
                    handlePaymentSuccess(paymentData);
                    break;
                case Activity.RESULT_CANCELED:
                    // Nothing to here normally - the user simply cancelled without selecting a
                    // payment method.
                    break;
                case AutoResolveHelper.RESULT_ERROR:
                    Status status = AutoResolveHelper.getStatusFromIntent(data);
                    handleError(status.getStatusCode());
                    break;
            }

            // Re-enables the Pay with Google button.
            mGooglePayButton.setClickable(true);
            break;
    }
}
























The function below demonstrates how to handle the payment request returned from the intent, and send on the necessary tokenized card details to the Judo API to be processed.

private void handlePaymentSuccess(PaymentData paymentData) {
    // PaymentMethodToken contains the payment information, as well as any additional
    // requested information, such as billing and shipping address.
    PaymentMethodToken token = paymentData.getPaymentMethodToken();

    // getPaymentMethodToken will only return null if PaymentMethodTokenizationParameters was
    // not set in the PaymentRequest.
    if (token != null) {
        String encryptedToken = token.getToken();
        String cardNetwork = paymentData.getCardInfo().getCardNetwork();
        String cardDetails = paymentData.getCardInfo().getCardDetails();

        JudoApiService apiService = getJudo().getApiService(getApplicationContext());
        GooglePayRequest request = getGooglePayRequest(encryptedToken, cardNetwork, cardDetails);
        apiService.googlePayPreAuth(request);
    }
}

private GooglePayRequest getGooglePayRequest(String encryptedToken, String cardNetwork, string cardDetails) {
    return new GooglePayRequest.Builder()
            .setJudoId("YOUR_JUDO_ID")
            .setGooglePayWallet(new GooglePayWallet.Builder()
                    .setCardNetwork(cardNetwork)
                    .setCardDetails(cardDetails)
                    .setToken(encryptedToken)
                    .build())
            .setAmount(YOUR_PRICE)
            .setCurrency(Currency.GBP)
            .setConsumerReference(UNIQUE_GUID)
            .build();
}


































Android

Getting started

Integrate simple and secure in-app card payments into your Android app. See our sample app for more information.

Judopay’s Out-of-the-box UI comes with built-in checks and security features, including real-time error detection, 3D Secure, data and address validation for frictionless card data capture.

This minimises PCI compliance and allows you focus on developing other areas of your app. See our UI customization guide below to learn more.

Integration

Requirements:

Installation of the Judopay Android SDK is simple using Android Studio, you don't need to clone a repository, just add the dependency to your app/build.gradle file:

compile 'com.judopay:android-sdk:5.6.10'




In your project-level build.gradle file you will need to add the Judopay Maven repository:

allprojects {
    repositories {
        jcenter()
        maven {
            url "http://dl.bintray.com/judopay/maven"
        }
    }
}












Setup

To start setting up your app, please complete all the relevant integration steps in the setup section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

If you have completed the setup section, start using Judopay’s Android SDK by adding your app’s token and secret to your app’s main Activity class:

Judo judo = new Judo.Builder()
    .setApiToken("<TOKEN>")
    .setApiSecret("<SECRET>")
    .setEnvironment(Judo.SANDBOX)
    .setJudoId("<JUDO_ID>")
    .setAmount("1.00")
    .setCurrency(Currency.GBP)
    .setConsumerReference("<YOUR_REFERENCE>")
    .build();













Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

If you require other payment types, such as reserving funds on a card to collect later, or server side refunds, please see the overview for all integration methods.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

Check payment result

You can quickly check the transaction results for the calling activity by overriding the onActivityResult method to receive the payment receipt:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(requestCode == Judo.PAYMENT_REQUEST) {
        switch (resultCode) {
            case Judo.RESULT_SUCCESS:
                Receipt receipt = data.getParcelableExtra(Judo.JUDO_RECEIPT);
                // success
        }
    }
}















Set Up Device DNA

To protect your app from fraud in real-time, Device DNA™ is an essential component of JudoShield that enables Judopay to capture data and device signals at the time of the transaction.

If you are integrating the ‘Mobile and your server side method’, you need to use Device DNA on the mobile in conjunction with your backend when making a payment:

Learn more about Device DNA™.

UI customization

Use Judopay’s Out-of-the-box UI components for a frictionless checkout in your app. Minimize your PCI scope with a UI that can be themed to match your brand colors.

Built-in features include quick data entry, optional security checks and fraud prevention that allow you to focus on developing other areas of your app. - Check out our guide to Customising Out-of-the-box UI. - For greater flexibility, learn about custom layouts.

The Judopay SDK also includes an API client for direct use of Judopay’s RESTful API. This offers the most options in terms of customization, but we recommend that you use the Judopay UI to minimise your PCI scope and development time.

Additional resources

Sample app

See the sample app on GitHub for examples on how to integrate the SDK (payments, pre-authorizations, token payments, etc).

Android Pay™

Android Pay is a simple and secure mobile payment solution for Android devices. It allows merchants to accept payments for goods and services. It also accesses buyers’ payment and shipping information from their Google accounts. The Judopay Android SDK lets your app process Android Pay payments, providing a frictionless checkout.

Requirements:

Card scanning

The Judo Android SDK works with card scanning libraries such as card.io. This allows users to quickly enter card data using the camera on their device.

Listing receipts

Judopay SDK also lets you request a list of payment receipts, with options to filter the results.

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow all the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In the Activity in your Android app that initializes the Judopay Android SDK, replace the environment with Judo.LIVE and use the live token and secret of your app.

Judo judo = new Judo.Builder()
  .setApiToken("<TOKEN>")
  .setApiSecret("<SECRET>")
  .setEnvironment(Judo.LIVE)
  .setJudoId("<JUDO_ID>")
  //...
  .build();











Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

Android Pay

How it works

Android Pay is a mobile payment solution that offers further simplicity, security and choice when making purchases with Android phones.

With Android Pay, merchants can accept payments for physical goods and services, and access buyers' shipping and payment information stored in their Google account. The Judopay Android SDK can be used to process Android Pay payments made in your app making the checkout journey even simpler and more secure.

Requirements

In order to operate successfully with Android pay, it requires devices working with an operating system Android OS 4.4 (KitKat) or newer.

User experience and interface

For consumers:

Each transaction is assigned a payment token as well as a Virtual Account Number, this information is encrypted and used in place of the credit or debit card details.

For businesses, Android Pay functions the same as any other debit or credit card payment processed with Judopay.

Getting started

Enabling Android Pay with Judopay requires a brief introduction from one of our payment experts, please contact us.

Please see our sample app for instructions for integrating Android Pay in your app.

iOS ObjC

Getting started

Integrate simple and secure in-app card payments into your iOS ObjC app with our Judopay SDK.

Judopay’s Out-of-the-box UI comes with built-in checks and security features, including instant error detection, real-time fraud prevention, 3D Secure, data and address validation for frictionless card data capture.

This minimises PCI compliance and allows you focus on developing other areas of your app. See the UI customization section below to learn more.

Integration

Requirements:

Add the Objective-C SDK to the top of the file where you want to use it:

#import <JudoKitObjC/JudoKitObjC.h>



Install Cocoapods with the following command:

$ gem install cocoapods



Add ‘JudoKitObjC’ to your Podfile to integrate it into your Xcode project.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
pod 'JudoKitObjC', '~> 6.2'





Install the new pod in your project:

$ pod install



In Xcode, go to the Project Navigator called ‘Pods’, select the JudoKitObjC target and open the tab called Build Phases. Add a new Run Script Phase and drag it above the Compile Sources build phase.

Include the following line in the shell script:

sh "${PODS_ROOT}/DeviceDNA/Framework/strip-frameworks-cocoapods.sh"



Setup

To start setting up your app, please complete all the relevant integration steps in the getting started section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

If you have completed the setup section, start using Judopay’s iOS Objective-C SDK by adding your app’s token and secret when initializing the SDK:

self.judoKitSession = [[JudoKit alloc] initWithToken:token secret:secret];



Instruct the SDK to communicate with sandbox environment by including the following line where the payment is initiated in the ViewController:

self.judoKitSession.apiSession.sandboxed = YES;



The SDK allows further configuration. These are the options:

Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

If you require other payment types, such as reserving funds on a card to collect later, or server side refunds, please see the overview for all integration methods.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

Set Up Device DNA

To protect your app from fraud in real-time, Device DNA™ is an essential component of JudoShield that enables Judopay to capture data and device signals at the time of the transaction.

If you are integrating the ‘Mobile and your server side method’, you need to use Device DNA on the mobile in conjunction with your backend when making a payment:

Learn more about Device DNA™.

UI customization

Use Judopay’s Out-of-the-box UI components for a frictionless checkout in your app. Minimize your PCI scope with a UI that can be themed to match your brand colors.

Built-in features include quick data entry, optional security checks and fraud prevention that allow you to focus on developing other areas of your app.

Check out our guide to Customising Out-of-the-box UI. The Judopay SDK also includes an API client for direct use of Judopay’s RESTful API. This offers the most options in terms of customization, but we recommend that you use the Judopay UI to minimise your PCI scope and development time.

Additional resources

Apple Pay™

Apple Pay provides an easy, secure, and private way to pay for physical goods and services in iOS apps. By simply using Touch ID, users can quickly and securely provide all their payment and shipping information to check out with a single touch. The Judopay iOS Objective-C SDK lets your app process Apple Pay payments, providing a frictionless checkout.

Requirements:

Card scanning

iOS Objective-C SDK works with card scanning libraries such as card.io. This allows users to quickly enter card data using the camera on their device.

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In your app’s ViewController, find and delete the following line that specifies the targeted environment:

self.judoKitSession.apiSession.sandboxed = YES;



Replace your sandbox API token and secret for the live API token and secret in the correspondent line. Both credentials are located in the dashboard, under the ‘Your apps’ section. Follow our Access token and secret guide if you need help to find them.

self.judoKitSession = [[JudoKit alloc] initWithToken:token secret:secret];



Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

iOS Swift

Getting started

Integrate simple and secure in-app card payments into your iOS Swift app with our Judopay SDK.

Judopay’s Out-of-the-box UI comes with built-in checks and security features, including real-time error detection, 3D Secure, data and address validation for frictionless card data capture.

This minimises PCI compliance and allows you focus on developing other areas of your app. See our UI customization guide to learn more.

Integration

Requirements:

Add the Swift SDK to the top of the file where you want to use it:

import JudoKit



Install Cocoapods with the following command:

$ gem install cocoapods



Add Judopay to your Podfile to integrate it into your Xcode project.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!
pod 'JudoKit', '~> 6.2'






Install the new pod in your project

$ pod install



In Xcode, go to the Project Navigator called ‘Pods’, select the JudoKit target and open the tab called Build Phases. Add a new Run Script Phase and drag it above the Compile Sources build phase.

Include the following line in the shell script:

sh "${PODS_ROOT}/DeviceDNA/Framework/strip-frameworks-cocoapods.sh"



Setup

To start setting up your app, please complete all the relevant integration steps in the getting started section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

If you have completed the setup section, start using Judopay’s iOS Swift SDK by adding your app’s token and secret when initializing the SDK:

var judoKitSession = JudoKit(token: token, secret: secret)



Command the SDK to communicate with sandbox environment by including the following line where the payment is initiated in the ViewController:

self.judoKitSession.sandboxed(true)



The SDK allows further configuration. These are the options:

Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

If you require other payment types, such as reserving funds on a card to collect later, or server side refunds, please see the overview for all integration methods.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

Set Up Device DNA

To protect your app from fraud in real-time, Device DNA™ is an essential component of JudoShield that enables Judopay to capture data and device signals at the time of the transaction.

If you are integrating the ‘Mobile and your server side method’, you need to use Device DNA on the mobile in conjunction with your backend when making a payment:

Learn more about Device DNA™.

UI customization

Use Judopay’s Out-of-the-box UI components for a frictionless checkout in your app. Minimize your PCI scope with a UI that can be themed to match your brand colors.

Built-in features include quick data entry, optional security checks and fraud prevention that allow you to focus on developing other areas of your app.

Check out our guide to Customising Out-of-the-box UI.

The Judopay SDK also includes an API client for direct use of Judopay’s RESTful API. This offers the most options in terms of customization, but we recommend that you use the Judopay UI to minimise your PCI scope and development time.

Additional resources

Apple Pay™

Apple Pay provides an easy, secure, and private way to pay for physical goods and services in iOS apps. By simply using Touch ID, users can quickly and securely provide all their payment and shipping information to check out with a single touch. The Judopay iOS Objective-C SDK lets your app process Apple Pay payments, providing a frictionless checkout.

Requirements:

Card scanning

iOS Objective-C SDK works with card scanning libraries such as card.io. This allows users to quickly enter card data using the camera on their device.

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In your app’s ViewController, find and delete the following line that specifies the targeted environment:

self.judoKitSession.sandboxed(true)



Replace your sandbox API token and secret for the live API token and secret in the correspondent line. Both credentials are located in the dashboard, under the ‘Your apps’ section. Follow our Access token and secret guide if you need help to find them.

var judoKitSession = JudoKit(token: token, secret: secret)



Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

Apple Pay

How it works

Apple Pay provides an easy, secure, and private way to pay for physical goods and services such as groceries, clothing, tickets, and reservations in your iOS apps. By simply using Touch ID, users can quickly and securely provide all their payment and shipping information to check out with a single touch.

Judopay’s iOS framework enables you to utilize Apple Pay within your iOS app. We provide the payment processing services that facilitate Apple Pay’s wallet solution. Apple Pay handles the secure storage of the device owner’s payment and shipping information, while Judopay processes the payments that Apple Pay initiates.

Requirements

Currently, Apple Pay can be used for physical goods and services using the following:

User experience and interface

For consumers, the Apple Pay experience starts with registering payment and shipping information into the Wallet app on their Apple devices. Once registered, consumers can pay simply and securely by using Touch ID to authenticate a transaction.

Each transaction processed through Apple Pay is assigned a one-time payment number as well as a dynamic security code. This information is encrypted and used in place of credit or debit card details.

Apple Pay offers consumers an exceptional level of ease, security and privacy. For businesses, Apple Pay functions the same as any other secure debit or credit card payment processed with Judopay.

Effective implementations of Apple Pay can radically improve your payment process by allowing for a smoother ‘guest checkout’, while still capturing all the relevant information needed to fulfil a purchase (such as shipping information).

The Apple Pay button

Apple Pay allows the user to bypass the standard checkout flow and complete their payment with speed:

While integrating Apple Pay, you’ll need to consider when you want to introduce the Apple Pay button, such as on a product listing page for a single item, within a basket page of multiple items, or in both of these scenarios.

The Apple Pay button indicates that users can make a purchase from their immediate context (i.e. the particular page they’re browsing). When users tap the Apple Pay button, the payment sheet should immediately be invoked to begin the checkout process. For more information on the Apple Pay button, see Apple’s guidance of the PKPaymentButton Class Reference.

The payment sheet

Before a user submits an order and initiates the payment, Apple Pay will display a payment sheet containing the contact, shipping and payment information relevant to the checkout being used.

Although users can make changes within the payment sheet - such as selecting a different shipping method - they shouldn’t have to make changes or enter additional information. When a user sees the payment sheet, they should be able to immediately authorize and complete their payment.

Customizing the payment sheet

You can customize the information displayed on the Apple Pay payment sheet depending on the information you require in order to complete the transaction and fulfill the order. When customizing the payment sheet, there are a few things to keep in mind:

  1. Make sure to display only the necessary information - Users may get concerned or confused if the Apple Pay sheet displays extraneous information. For example, requesting a shipping address is perfectly acceptable for mail order companies where there is a valid need for this information, but if this information isn’t required for fulfilment of the order you shouldn’t request it.
  2. Let users choose their delivery method within the payment sheet - Users can select a delivery method from a list that you specify within the Apple Pay payment sheet. To specify a shipping method, you’ll need to use a label, a cost, and an optional second line for providing a delivery estimate.
  3. Use line items for recurring payments and for charges that are added to the merchandise being purchased - A line item will consist of a label and a cost. It conveys additional information about the breakdown of charges in the user’s purchase. Use line items to:
    1. Indicate that a user is authorizing a recurring payment with a line item like ‘Monthly subscription £19.99’
    2. Notify the user of extra charges, for example: ‘Gift Wrap £5.00’ or ‘Tax £4.53’
    3. Show a coupon or discount that has a negative cost, such as ‘Friday Discount -£2.00’
  4. Create line item labels that can display on a single line - Where possible we recommend using concise and readily understandable labels.
  5. Provide a business name after ‘PAY’ on the same line as the total - This will help reassure users their payment is going where they expect it to.
  6. Communicate possible additional costs if applicable - Users can authorize Apple Pay payments for services without knowing the total amount, such as a taxi journey. It’s important to clearly explain within the payment sheet that there may be additional costs. Equally, if you are pre-authorizing funds to collect later, this too should be represented within the payments sheet.

If you have any questions on your Apple Pay integration, contact one of our payment experts for a consultation.

Testing best practices

There’s currently no available test environment for Apple Pay, which means you’ll need to complete your testing stories within the production environment.

We strongly recommend testing Apple Pay through each of these scenarios before you release the app:

Getting started

This section steps through the details for implementing Apple pay.

Create a merchant ID

  1. Access your Apple Developer Account and visit the 'Certificates, Identifiers & Profiles' section of the Apple member center. You can then navigate to 'Merchant IDs' and click 'add.'
  2. Set your Merchant ID. The identifier you enter should be a reverse DNS style identifier prefixed with the word

Create an Apple Pay certificate

  1. Request a 'certificate signing request' (CSR file) from Judopay by emailing developersupport@judopayments.com.
  2. When you’ve received your 'certificate signing request', you’ll need to proceed with creating your Apple Pay certificate. You can do this within the Apple member center either under 'Certificates > All' or from the Merchant ID page. The first screen will describe how to manually create your certificate signing request. As you’ve already obtained this from Judopay, you can click 'Continue'. Apple will ask you if you are processing transactions outside of the United States. At this point, you should select "No".
  3. You’ll then be prompted to upload the CSR file provided by Judopay and then click 'Generate'. You should then receive confirmation that your certificate is ready:
  4. You’ll need to download this certificate and send it to Judopay in order to complete your Apple Pay set-up. When we’ve received this certificate, we’ll add it to your account and notify you to confirm it’s been added.

Setup your Apple Pay entitlement

  1. Apple Pay is built into the PassKit framework, but it has it’s own entitlement which you’ll need to configure. You can do this by selecting your build Target and then selecting ‘Capabilities’ as shown below:
  2. Once you’ve enabled the entitlement, you’ll need to add the Merchant ID you created earlier to the app (you may need to refresh the list):
  3. When you’ve done this, we recommend opening the entitlements file to confirm the Merchant ID has been added to your app:

And that’s it! Your account is now ready to process Apple Pay payments with Judopay. You can configure the Judopay SDK to proceed making payments by following the tutorial below.

Check for Apple Pay support

Apple Pay is not supported on all Apple devices. Before invoking any Apple Pay functionality within your app, you’ll need to test if it’s supported on the device.

Apple provide two methods for performing these checks:

  1. You can use [PKPaymentAuthorizationViewController canMakePayments] to check if the user’s device supports Apple Pay and has it enabled. This check will query both the device hardware and whether Apple Pay is enabled in the user’s region.
  2. Using [PKPaymentAuthorizationViewController canMakePaymentsUsingNetworks] provides a more detailed check to query whether a user has a registered card with particular card schemes. This check is useful if you don’t accept all card types.

Both methods are explained in detail in the Apple developer documentation here.

Perform a payment

Use the live environment for testing Apple Pay before deploying your app to the public. Please consult the best test practices in our live environment guide. Here some highlights:

Test live payments

Create a payment intent with the required extras as per the following guides, depending on the SDK used in your integration:

See our iOS · ObjC guide.

See our iOS · Swift guide.

After you have completed all these steps and are satisfied with the testing, you are ready to start taking payments through Apple Pay!

Xamarin

Getting started

Integrate simple and secure in-app card payments into your app with the Judopay Xamarin SDK.

Judopay’s Out-of-the-box UI comes with built-in checks and security features, including instant error detection, real-time fraud prevention, 3D Secure, data and address validation for frictionless card data capture.

This minimises PCI compliance and allows you focus on developing other areas of your app. See the UI customization section below to learn more.

Integration

Requirements:

The SDK is compatible with Android Jelly Bean (4.1) and above and iOS 8 and above.

You can integrate Judopay into your project by visiting the Xamarin component store, then search for ‘Judopay’ and add the component to your app, Android and iOS projects.

Setup

To start setting up your app, please complete all the relevant integration steps in the getting started section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

If you have completed the setup section, start using Judopay’s Xamarin SDK by adding your app’s token and secret to your newly created Judo instance in your Xamarin Forms page:

var judo = new Judo()
{
    JudoId = "<JUDO_ID>",
    ApiToken = "<API_TOKEN>",
    ApiSecret = "<API_SECRET>",
    Environment = JudoEnvironment.Sandbox,
    Amount = 1.50m,
    Currency = "GBP",
    ConsumerReference = "YourUniqueReference"
};












You will need to add additional configuration depending on the project you are integrating:

Android Due to a bug in Xamarin.Forms for Android that results in the page not resizing correctly when the keyboard is visible, an additional piece of code must be added to your Android Activity.

Add the code snippet after the Xamarin.Forms.Forms.Init method call inside the ‘OnCreate’ method of your Activity:

Window.SetSoftInputMode(SoftInput.AdjustResize);
AndroidBugfix5497.assistActivity(this);




iOS

Xamarin.Forms for iOS has issues resolving dependencies using DependencyService unless they have been registered.

Add this in your AppDelegate.cs after the LoadApplication(new App()) method call in your FinishedLaunching method:

DependencyService.Register<ClientService>();
DependencyService.Register<HttpClientHelper>();
// Required if using Apple Pay
DependencyService.Register<ApplePayService>();






The SDK allows further configuration by usiung the existing Judo.Builder settings. These are the options:

Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

If you require other payment types, such as reserving funds on a card to collect later, or server side refunds, please see the overview for all integration methods.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

UI customization

Use Judopay’s Out-of-the-box UI components for a frictionless checkout in your app. Minimize your PCI scope with a UI that can be themed to match your brand colors.

Built-in features include quick data entry, optional security checks and fraud prevention that allow you to focus on developing other areas of your app. - Check out our guide to Customising Out-of-the-box UI.

The Judopay SDK also includes an API client for direct use of Judopay’s RESTful API. This offers the most options in terms of customization, but we recommend that you use the Judopay UI to minimise your PCI scope and development time.

Additional resources

Sample app

See the sample app on GitHub for examples on how to integrate the SDK (payments, pre-authorizations, token payments, etc).

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In the Judo instance within your app’s Xamarin Forms page, find and change the following line that specifies the targeted environment from SANDBOX to LIVE:

Environment = JudoEnvironment.Live,



Replace your sandbox API token and secret for the live API token and secret in the correspondent lines in the same Judo instance. Both credentials are located in the dashboard, under the ‘Your apps’ section. Follow our Access token and secret guide if you need help to find them.

ApiToken = "<API_TOKEN>",
ApiSecret = "<API_SECRET>",




Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

Server SDKs

This section contains step by step tutorials for integrating with Judo using our server-side SDKs. Each guide will cover the basics from the initial set up and development steps, additional configuration options, all the way through to going live and testing your app.

Dot Net

Easily handle simple and secure payments on your back-end with the Judopay .NET server side SDK.

Integration

Using Visual Studio, launch the NuGet Package Manager and search for JudoPay.Net and add it through the GUI, or in the Package Manager Console and add the JudoPay.Net package:

Install-Package JudoPay.Net

Setup

To start setting up your app, please complete all the relevant integration steps in the setup section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

When you have completed the setup, start using Judopay’s .NET SDK by adding your app’s token and secret when initializing the SDK:

var client = JudoPaymentsFactory.Create<JudoEnvironment.Sandbox, "YOUR_API_TOKEN", "YOUR_API_SECRET">;





Remember, if you perform payments only from your backend, you should only enable the ‘Register Card Transactions’ permission for your app and create a separate app for your backend with only the ‘Make Payments’ permission enabled.

Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

Set Up Device DNA

To protect your app from fraud in real-time, Device DNA™ is an essential component of JudoShield that enables Judopay to capture data and device signals at the time of the transaction.

If you are integrating the ‘Mobile and your server side method’, y ou need to use Device DNA on the mobile in conjunction with your backend when making a payment:

To setup Device DNA for your server side SDK please follow the Getting started guide. To setup Device DNA for your mobile app, please follow the Getting started guides for iOS, Android.

Learn more about Device DNA™.

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In the JudoPaymentsFactory.Create method, find and change the environment from ‘Sandbox’ to ‘Live’.

Replace your sandbox API token and secret for the live API token and secret in the corresponding lines in the main Activity class. Both credentials are located in the dashboard, under the ‘Your apps’ section. Follow our Access token and secret guide if you need help to find them.

var client = JudoPaymentsFactory.Create(JudoEnvironment.Live, "YOUR_API_TOKEN", "YOUR_API_SECRET");





Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

PHP

Easily handle simple and secure payments on your back-end with the Judopay PHP server side SDK.

Integration

Requirements:

Using Composer Package Manager, add the Judopay package to your composer.json file:

"require": {
    "judopay/judopay-sdk": "~2.0"
}





Then execute:

$ composer install



Make the Judopay SDK classes available within your application by requiring the ‘vendor/autoload.php’ file.

See Composer for more information on getting started.

Setup

To start setting up your app, please complete all the relevant integration steps in the setup section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

When you have completed the setup, start using Judopay’s PHP SDK by adding your app’s token and secret when initializing the SDK:

$judopay = new \Judopay(
    array(
        'apiToken' => 'your-token,
        'apiSecret' => 'your-secret',
        'judoId' => 'your-judo-id',
        //Set to true on production, defaults to false which is the sandbox
        'useProduction' => false
    )
);











Remember, if you perform payments only from your backend, you should only enable the ‘Register Card Transactions’ permission for your app and create a separate app for your backend with only the ‘Make Payments’ permission enabled.

The SDK allows further configuration. These are the options:

Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

Set Up Device DNA

To protect your app from fraud in real-time, Device DNA™ is an essential component of JudoShield that enables Judopay to capture data and device signals at the time of the transaction.

If you are integrating the ‘Mobile and your server side method’, y ou need to use Device DNA on the mobile in conjunction with your backend when making a payment:

Learn more about Device DNA™.

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In the Judopay object, find and change the production environment setting from ‘false’ to ‘true’.

Replace your sandbox API token and secret for the live API token and secret in the corresponding lines. Both credentials are located in the dashboard, under the ‘Your apps’ section. Follow our Access token and secret guide if you need help to find them.

$judopay = new \Judopay(
    array(
        'apiToken' => 'your-token,
        'apiSecret' => 'your-secret',
        'judoId' => 'your-judo-id',
        //Set to true on production, defaults to false which is the sandbox
        'useProduction' => true
    )
);











Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

Ruby

Easily handle simple and secure payments on your back-end with the Judopay Ruby server side SDK.

Integration

Requirements:

Add the following line to your application’s Gemfile:

gem 'judopay'



Once the Gemfile is set, then there are two options to finish the installation:

$ bundle



- Or install it yourself as:

$ gem install judopay



Setup

To start setting up your app, please complete all the relevant integration steps in the setup section. By following these steps, you are ensuring that your app will be secure and frictionless for you and your customers.

When you have completed the setup, start using Judopay’s PHP SDK by adding your app’s token and secret when initializing the SDK:

Judopay.configure do |config|
  config.judo_id = 12345
  config.api_token = 'your-token'
  config.api_secret = 'your-secret'
  # Set to true on production, defaults to false which is the sandbox
  config.use_production = false
end










Remember, if you perform payments only from your backend, you should only enable the ‘Register Card Transactions’ permission for your app and create a separate app for your backend with only the ‘Make Payments’ permission enabled.

The SDK allows further configuration. These are the options:

Payment types

Setup the payment types you require for your app. Depending on your chosen integration method you have a variety of payment types.

Test sandbox payments

Test your app quickly and securely with different payment types. The Sandbox testing guide will provide you all the details you need to ensure a solid integration. Here are some highlights:

Set Up Device DNA

To protect your app from fraud in real-time, Device DNA™ is an essential component of JudoShield that enables Judopay to capture data and device signals at the time of the transaction.

If you are integrating the ‘Mobile and your server side method’, y ou need to use Device DNA on the mobile in conjunction with your backend when making a payment:

Going live

Ensure a stress-free launch of your app by testing all transaction types you require in the live environment.

If you haven’t tested your app in sandbox environment yet, please follow the above sections for this SDK before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In the Judopay gem, find and change the production environment setting from ‘false’ to ‘true’.

Replace your sandbox API token and secret for the live API token and secret in the corresponding lines. Both credentials are located in the dashboard, under the ‘Your apps’ section. Follow our Access token and secret guide if you need help to find them.

Judopay.configure do |config|
  config.judo_id = 12345
  config.api_token = 'your-token'
  config.api_secret = 'your-secret'
  # Set to true on production, defaults to false which is the sandbox
  config.use_production = true
end










Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

Additions (Embed Iframe)

Judo Additions is our Javascript solution which allows you to embed a card payments iframe seamlessly into your checkout page.

Your customer will enter their card number, expiry and CV2 into fields hosted by Judo. We then provide you with a one-use token which you use to pay from your back-end, without ever touching the sensitive payment information.

To see how this integration method works, please see our documentation in github.

Web Payments

Integrate simple and secure web app card payments into your project with web payments optimized for mobile screens.

Judopay’s web payments UI come with built-in checks and security features, including real-time error detection, 3D Secure, data and address validation for frictionless card data capture. This minimises PCI compliance and lets you focus on developing other areas of your user experience. See the UI customization part of this section to learn more.

Web payments use the same protocols and environments as the standard Judopay API. Learn more about this in our RESTful API · Web payments reference.

Web Payments Setup

Web payments require two configurations of your account. Both settings can be enabled in the dashboard:

Build the transaction header before your payment request. Find your account’s API token and secret on the dashboard and add them to the basic authorization object, base64 encoded:

Http Header

POST https://gw1.judopay-sandbox.com/webpayments/payments
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password). If you are looking to use any of the following options, these require additional configuration:

Test sandbox web payments

Test different payment types quickly and securely. The sandbox environment guide will provide you critical detail to ensure a solid integration and successful results. These are the highlights:

Request a transaction

Create a transaction request including all the mandatory objects. Check our RESTful API · Web payments reference to learn more about this request. The details in the following snippet are dummy data – use the data of your account instead:

{
"judoId":"100016172",
"amount": 125.00,
"currency": "GBP",
"yourConsumerReference": "example_customer_reference_00001",
"yourPaymentReference": "example_payment_reference_00001",
"yourPaymentMetaData":{
"invoiceNumber": "000546" ,
"customerNumber": "ABC123456"
},
"clientIpAddress": "127.0.0.1",
"clientUserAgent": "example browser 5.25"
}

Retrieve Judopay’s API response:

"postUrl": "https://pay.judopay-sandbox.com/v1",
"reference": "yth67_82nhjmf903jnmaiine…"

Wrap your checkout button with a ‘form’ tag, using the postUrl as the form’s action and the reference as a hidden field:

<form action="{postUrl}" method="post">
<input id="Reference" name="Reference" type="hidden" value="{reference}">
<input type="submit" value="Pay now">
</form>

The consumer will be redirected to Judopay’s hosted secure web payments form where the card details will be requested.

Once the transaction is completed, the consumer will be redirected to your designated success or failure URL. This call will include some extra data in the POST request to your success URL (“application/x-www-form-urlencoded”), including: 1. Receipt ID – a unique identifier for that particular transaction. 2. Card token - a unique to allow you to perform repeat payments. 3. Reference – a transaction key to check the result of a payment and get the receipt information.

Check payment results and receipts

You can quickly check the transaction result by sending a request to our API using the designed reference provided after the first payment request (above):

GET https://partnerapi.judopay-sandbox.com/webpayments/{reference}

You will receive your receipt information from our API as per the following example:

{
"amount": 1.01,
"cardAddress": {
"countryCode": 826
},
"clientIpAddress": "127.0.0.1",
"clientUserAgent": "Mozilla/5.0 (Windows NT 6.2; Win64; x64)...",
"companyName": "trading",
"currency": "GBP",
"expiryDate": "2015-11-13T14:47:52.1183+00:00",
"judoId": "100337815",
"partnerServiceFee": 1.01,
"paymentCancelUrl": "http://www.marca.com/",
"paymentSuccessUrl": "http://www.20minutos.es/",
"reference": "3wcAAAsAAAANAAAADgAAAJ_C3aHop-cZcb5PTdUGOH8ceQ1_wn8fP46UmY_CWYMZ8jcUgA",
"allowedCardTypes": [
1,
2,
3,
8,
10,
11,
12,
13
],
"response": {
"postUrl": "https://pay.judopay-sandbox.com/v1",
"reference": "3wcAAAsAAAANAAAADgAAAJ_C3aHop-cZcb5PTdUGOH8ceQ1_wn8fP46UmY_CWYMZ8jcUgA"
},
"status": "Expired",
"transactionType": "SALE",
"yourConsumerReference": "001",
"yourPaymentMetaData": {},
"yourPaymentReference": "003",
"webPaymentOperation": 0
}

On your receipt screen we recommend displaying the order information, including:

UI customization

Use our web payments UI for a frictionless web checkout on mobile. Minimize your PCI scope with a UI that can be customized to display:

To request a customisation for the above, please contact us.

Judopay also includes an API client for direct use of our RESTful API. This offers the most options for customization, but we recommend that you use our secure payments form to minimise your PCI scope and development time.

Going Live With Web Payments

Ensure a stress-free launch of your web app by testing all transaction types you require in the live environment.

If you haven’t tested your app in the sandbox environment yet, please visit the Getting started guide before proceeding.

Activate your account

You will need a live account to process live payments. Follow the Activate your account guide.

Point to live environment

In your header declaration, find and change the line that specifies the targeted environment by deleting ‘-sandbox’ on the URL.

Replace your sandbox API token and secret for the base64 encoded live API token and secret in the corresponding basic authorization line. Both credentials are located in your Dashboard, under the ‘Your apps’ section.

Follow our Access to your token and secret guide if you need help to find them.

Http Header

POST https://gw1.judopay.com/webpayments/payments
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}
You should replace {authstring} with the base64 encoding of your API token (username) followed by a colon and then your API secret (password).

Test live payments

As per the sandbox, use the live environment for testing before deploying your app to the public. Please follow the testing best practices in the Live testing guide. Here are some highlights:

Go live

To help you integrate and test your project, use the sandbox and live environments before release.

This document outlines the best practices to ensure that you are fully testing payments in both environments to avoid surprises and unexpected behaviours once the app is deployed to your consumers.

Account activation

Before you activate your account, ensure that you have tested your app in the sandbox environment and confident that everything is working as expected.

To process live payments, you’ll need to activate your account so that you can access live API tokens and secrets for your apps. This is a quick and easy process:

  1. Login to your dashboard.
  2. Select ‘Activate account’ and complete the registration form.
  3. Select your pricing package and click ‘Submit’.
  4. Your Live token and secret can now be found in the dashboard by opening the ‘Your apps’ tab, selecting your added application, and clicking ‘Live token’.
  5. Once this process is done, we will receive your request to go live and will perform the necessary changes in your account to start processing live payments. We will contact you within one working day once you are ready to go.

Live testing

After you have activated your account, we recommend to test in the live environment performing all the scenarios you completed in sandbox before you release to ensure everything is working as expected.

Use real cards for live testing

You can’t use test cards in the live environment. When testing in live, use real credit/debit cards, by processing small amounts (minimum £1.01 to avoid unexpected declines).

Common test scenarios

Test your application with all the required payment types: e.g. register a card and repeat card (token) payment.

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.

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:

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.

Web payments

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

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:

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

Errors

The Judopay API uses the following error codes:

Code Description
0 Sorry, an error has occurred. Please try again later.
1 Sorry, we're unable to process your request. Please check your details and try again.
7 Sorry, we were unable to authorize this request. Please check your details and permissions before trying again.
9 Sorry, we were unable to process your payment. Please try again later.
11 Sorry, we were unable to process your payment at this time. Your card has not been charged.
12 Sorry, we were unable to process your payment. Please check your details and try again.
19 Sorry, but the transaction specified was not found.
20 Validation passed successfully.
21 Sorry, an error has occurred. Please try again later.
22 Sorry, an error has occurred. Please try again later.
23 Please ensure your 'From' date is in dd/mm/yyyy format.
24 Please ensure your 'To' date is in dd/mm/yyyy format.
25 We were unable to find the webpayment identified by this reference
26 Sorry, an error has occurred. Please try again later.
27 This endpoint is not available as the Api-Version requested is too low.
28 This endpoint is not available as it has been deprecated for the Api-Version requested.
31 This endpoint is only available if the account is enabled to use the Judo Card Vault.
39 API-Version not supported
40 Sorry, but the API version you are targeting is invalid. Please review this and try again.
41 Sorry, but the API-Version is missing from your header. Please check your details and try again.
42 Sorry, it looks like the PreAuth you are referencing has expired.
43 Sorry, it looks like you're trying to make a collection on an invalid transaction type. Collections can only be performed on PreAuths.
44 Sorry, it looks like the currency you're specifying doesn't match your original transaction.
45 Sorry, this transaction has been voided. You cannot perform a collection on a voided transaction.
46 Sorry, but the amount you're trying to collect is greater than the pre-auth
47 Sorry, but it looks like the transaction you are trying to refund is invalid. Refunds can only be performed on Sales and Collections.
48 Sorry, this transaction has been voided. You cannot perform a refund on a voided transaction.
49 Sorry, but the amount you're trying to refund is greater than the original transaction.
50 Sorry, but it looks like the original transaction you're specifying is an invalid type for the request you're trying to perform.
51 Sorry, but it looks like the transaction you are trying to void has already been voided.
52 Sorry, but it looks like the transaction you are trying to void has already been collected.
53 Sorry, but it looks like the void you are trying to process is for a different amount than the original preauth.
54 Sorry, but we are currently unable to accept payments to this account. Please contact customer services.
55 Sorry, we're unable to find the judo ID specified. Please confirm your judo ID and try again.
56 Sorry, but the transaction specified was not found. Please check your details and try again.
57 Sorry, but there was no consumer found for the transaction specified. Please check your details and try again.
58 Sorry, but this transaction does not require 3D-Secure authorization. Please check you're sending authorization to the correct transaction.
59 Sorry, but it looks like this transaction has already been authorised via 3D-Secure.
60 3D-Secure was not successful for this transaction.
61 We've been unable to decrypt the supplied Apple Pay token. Please check your API client configuration in the dashboard.
62 Sorry, we were unable to find the transaction you have referenced in your request.
63 Sorry, but the transaction you are referencing was not successful.
64 Sorry, but it looks like you're using a test card. Only real cards are valid in this environment.
65 Sorry, but the collection request you've specified is not valid. Please check your details and try again.
66 Sorry, but we were unable to find your original transaction to refund. Please check your details and try again.
67 Sorry, but your refund request was not valid. Please check that the original transaction was a Sale or Collection, has not previously been refunded, was not for a lesser amount than your refund request.
68 Sorry, but your void request is not valid. Please check your details and try again.
69 Our server encountered a problem when processing your transaction.
70 Sorry, but it looks like the card token specified is not valid. Please check your details and try again.
71 Sorry, an error has occurred. Please try again later.
72 Sorry, we're currently unable to route this transaction. Please check your account details and try again. If this issue persists, please contact customer services.
73 Sorry, but this card type is not currently supported on this account.
74 The CV2 entered is invalid.
75 Sorry, but the Card Token specified does not match the Consumer it was originally generated against. Please check your records and try again.
76 Sorry, but it appears the web payment reference you've specified is not valid.
77 Judo id not found, please check the judo id.
78 Sorry, but you are attempting to register a card with an incorrect transaction type. Please check your details and try again.
79 Sorry, but it looks you're trying to register this card with an invalid amount. Please check the amount of your request and try again.
80 Sorry, but the content-type was not specified or is currently unsupported. Currently only application/json is supported.
81 Sorry, we encountered an error while authenticating your request. Please check your authentication details and try again. If this issue continues, please contact customer services.
82 Sorry, the transaction you've specified has not been found. Please check your details and try again.
83 Sorry, the resource you are targeting has not been found. Please review your endpoints and try again.
84 Sorry, it looks like permissions are not enabled to perform this request. Application permissions can be configured in the judo Dashboard.
85 The content-type was not specified or is unsupported for the request made to the Judopay API. Currently supported content-type is limited to application/json.
86 Sorry, this payment has been stopped as it is a duplicate transaction.
130 We've been unable to decrypt the supplied Visa Checkout payload. Please confirm the public key in your app and check your API client configuration in the dashboard.
140 Something went wrong encryting card details. We apologise for any inconvenience caused. Please try again later
150 We've been unable to decrypt the supplied Encrypted payload. Please ensure the message has not been modified.
151 The encrypted blob is for another account.
152 Something went wrong retrieving card details. We apologise for any inconvenience caused. Please try again later
153 The one time token is not valid. It could have expired. Please try again
154 Your provided consumer reference is incorrect, please check your details and try again.
400 We've been unable to decrypt the supplied Android Pay wallet. Please confirm the public key in your app and check your API client configuration in the dashboard.
403 Sorry, but we were unable to authenticate your request. Please check your details and try again.
404 Sorry, but the requested resource was not found. Please check your details and try again.
601 Unable to decrypt the Google Pay payload.
602 Unable to access the Google Pay decryption service, please try again later.
603 Non-tokenized Google Pay cards not supported. Please verify the card can be tokenized for contactless Google Pay payments.
4002 Sorry, you cannot process marketplace preauths without using the Access Token. For more information please contact customer services.
20000 Sorry, but the ApplicationModel must not be null. Please check your details and try again.
20001 Sorry, but the Application Reference must not be null. Please check your details and try again.
20002 Sorry, but this application has already gone live and cannot be updated via this endpoint.
20003 Sorry, but the product selection is missing. Please check your details and try again.
20004 Sorry, but this application has already gone live and cannot be updated via this endpoint.
20005 Sorry, but you have not set your Api Application Rec ID.
20006 Sorry, but this request is not formatted correctly. Please review your request and try again.
20007 Sorry, but no application was found for the reference you supplied. Please check your details and try again.
20008 Sorry, but the file type specified is not currently supported.
20009 Sorry, there was an error with the file upload. Please try again later.
20010 Sorry, but the Application Reference must not be empty. Please supply a reference and try again.
20011 Sorry, but an application with the Application Reference supplied was not found. Please check your details and try again.
20013 Sorry, but you have not specified a sort type. Valid sort types include time-descending and time-ascending.
20014 Sorry, but the page size needs to include at least one record per page.
20015 Sorry, but the page size is currently limited to 500 or less.
20016 Sorry, but the offset supplied needs to be greater than zero.
20017 Sorry, but the Merchant ID supplied was not found. Please check your details and try again.
20018 Sorry, but the Merchant ID supplied was not found. Please check your details and try again.
20019 Sorry, no Products were found. Please check your details and try again.
20020 Sorry, but only a judo partner can submit simple applications. Please contact customer service.
20021 We're unable to parse this document, please ensure it conforms to our API requirements and then try again.
20022 Sorry, something went wrong, please check your authentication details and judo, then try again.
20023 To create a web payment, you'll need to perform a POST to the URL.
20025 Sorry, but MD parameter specified is invalid. Please check your details and try again.
20026 The receipt ID specified is not valid for the request you are attempting.
20027 Email address or password incorrect
20028 Permanent Lockout - We detected suspicious activity on this account and have locked it for your protection. Please contact our customer service team on 0203 503 600 to unlock your account.
20029 Temporary Lockout - We detected suspicious activity on this account and have locked it for your protection. Your account has been locked for {0} minutes.
20030 Sorry, this account does not currently support the requested currency. Please contact customer services for more information.
20032 Sorry, this email address is already in use.
667003 WebPayment reference is invalid
667004 JudoId not found, please check the judo id.
667005 This account is currently unable to accept payments. Please contact customer services.