Android

Integrating Android with Judopay

Prerequisites

You have set up your Judopay account.

Your judoIds and tokens are configured and enabled as appropriate.

For more information on permissions, see Permissions.

You have the latest version of the Android SDK.

For Mobile apps, we recommend using payment session authenticationpayment session authentication.

Integration Requirements

Android Studio and Build Tools - (We recommend you use the latest stable version).

Your app targets API 32 or higher.

Always consider Google's Play Store requirements.

Minimum Android SDK version 21 (Android 5.0).

The Mobile SDK is available for Android as a Gradle dependency. No need to clone a repository.

To add Judopay as a dependency to your current project:

Navigate to your build.gradle file

In the dependencies section add the latest com.judopay:judokit-android:{version} For the latest version, see Android Releases.

An example of how your build.gradle might look:

android { ... } dependencies { ... implementation 'com.judopay:judokit-android:4.0.1' ... }

3. Ensure the Maven Central Repository has been added:

allprojects { repositories { mavenCentral() } }

See Judopay's JudoKit for Android on Github.

Initialising the Judo Builder

The Judo builder is at the heart of the Android Mobile SDK. This class is responsible for:

Setting all the required parameters

Customising the payment flow

Import some of the classes and properties from the com.judopay.judokit.android package as detailed below:

import com.judopay.judokit.android.Judo import com.judopay.judokit.android.model.Amount import com.judopay.judokit.android.model.Reference import com.judopay.judokit.android.model.PaymentWidgetType import com.judopay.judokit.android.PAYMENT_CANCELLED import com.judopay.judokit.android.PAYMENT_ERROR import com.judopay.judokit.android.PAYMENT_SUCCESS import com.judopay.judokit.android.JudoActivity

Judo is the class used to build the payment flow.

Amount and Reference: Classes used to set the amount and reference properties.

PaymentWidgetType allows for multiple payment types:

Card

Google Pay™

Identifies the transaction result:

PAYMENT_SUCCESS

PAYMENT_ERROR

PAYMENT_CANCELLED

The JudoActivity class is used to start a payment intent.

Building the Judo Object

Set up the Transaction Amount

In the Amount object provide the Amount value and Currency type:

val amount = Amount.Builder() .setAmount("150.50") .setCurrency(Currency.GBP) .build()

Set up the Transaction Reference

In the Reference object provide the ConsumerReference string:

val reference = Reference.Builder() .setConsumerReference('my-consumer-reference') .build()

Set up the Judo Configuration

Set the following required parameters:

The token and secret values, OR create the authorisation object (Step 3 below).

Set the SDK to run in sandbox mode

Set the following objects:

Judo ID

JudoId format = 100100100

Authorisation object (if using this method)

Amount

Reference

Create the authorisation object:

Merchants operating in specific money movement and financial services categories, as defined by the card schemes must include additional data in the payment sessionpayment session. For more information, see Account Funding Transactions.

val authorization = PaymentSessionAuthorization.Builder() .setPaymentSession(paymentSession) .setApiToken(token) .build()

4. Set the authorisation object when invoking Judo builder:

val builder = Judo.Builder(widgetType) .setAuthorization(authorization)

Field	Description
CARD_PAYMENT	Card Payment
TOKEN_PAYMENT	Starts a token payment with optionally asking the user to enter their CSC and / or cardholder name.
PRE_AUTH	Card PreAuth
TOKEN_PRE_AUTH	Starts a pre-auth token payment with optionally asking the user to enter their CSC and / or cardholder name.
CREATE_CARD_TOKEN	Save Card
CHECK_CARD	Check Card
PAYMENT_METHODS	Payment Method Selection
PRE_AUTH_PAYMENT_METHODS	PreAuth Method Selection
GOOGLE_PAY	Google Pay (Payment)
PRE_AUTH_GOOGLE_PAY	Google Pay (PreAuth)
SERVER_TO_SERVER_PAYMENT_METHODS	Server to Server

The Judo object is now configured and you are ready to make a transaction.

Making a Transaction

Each transaction operation is represented as an Activity.

To make a transaction:

Create an Intent to pass the JudoActivity class

Add the Judo object to the Intent:

Call putExtra

Assign it to the JUDO_OPTIONS key

The Judo object holds all the payment configurations previously set up.

3. Pass the Intent and a request code to allow Judopay to handle the onActivityResult and the transaction response:

val intent = Intent(this, JudoActivity::class.java); intent.putExtra(JUDO_OPTIONS, judo); startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE);

4. Implement the onActivityResult method and handle the transaction response:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == JUDO_PAYMENT_WIDGET_REQUEST_CODE) { when (resultCode) { PAYMENT_CANCELLED -> toast("User cancelled the payment.") PAYMENT_SUCCESS -> { val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT) // Handle response } PAYMENT_ERROR -> { val error = data?.getParcelableExtra<JudoError>(JUDO_ERROR) // Handle error } } } }

Check the request code from the onActivityResult and see if it matches with JUDO_PAYMENT_WIDGET_REQUEST_CODE. If it does, the result is called from the JudoActivity.

This means the imported response codes can be used to check the following possible response type and handle each case respectively:

success

cancel

error

Android Server to Server Transactions

To set a server-to-server transaction:

On the Judo builder set the PaymentWidgetType to:

val judo = Judo.Builder(PaymentWidgetType.SERVER_TO_SERVER_PAYMENT_METHODS) .setApiToken("my-token") .setApiSecret("my-secret") .setIsSandboxed(true) .setJudoId("my-judo-id") .setAmount(amount) .setReference(reference) .build()

Token Payments

If you are building your own card wallet, and not using a UI you can make a preauth or payment using a stored card token.

Follow the steps for Making a Transaction and replace the PaymentWidgetType with:

PaymentWidgetType.TOKEN_PRE_AUTH or

PaymentWidgetType.TOKEN_PAYMENT

For more information on token payments, see the Android Sample App.

Setting up Recurring Payments

Make sure you are using:

Android SDK Version 7.2.0 (or higher)

Integration via React Native Mobile SDK is not currently supported.

Judopay supports Merchant Initiated Transactions (MIT)s for Wallet Customer Initiated Transactions (CIT)s.

Recurring Payments

To trigger an initial transaction that allows you to set up a Google Pay™ recurring payment token for future Merchant Initiated Transactions (MIT):

The MIT parameters are attached to GooglePayConfiguration via setRecurringParameters(...) (GooglePayRecurringParameters)

Set the first-charge-now flag: Judo.Builder.setInitialRecurringPayment(true)

Build the Judo object with PaymentWidgetType.GOOGLE_PAY (or PRE_AUTH_GOOGLE_PAY) and start the SDK activity:

import com.judopay.judokit.android.Judo
import com.judopay.judokit.android.model.GooglePayConfiguration
import com.judopay.judokit.android.model.PaymentWidgetType
import com.judopay.judokit.android.model.googlepay.GooglePayEnvironment
import com.judopay.judokit.android.model.googlepay.GooglePayIntroductoryPeriodInfo
import com.judopay.judokit.android.model.googlepay.GooglePayPriceStatus
import com.judopay.judokit.android.model.googlepay.GooglePayRecurrencePeriod
import com.judopay.judokit.android.model.googlepay.GooglePayRecurrencePeriodItem
import com.judopay.judokit.android.model.googlepay.GooglePayRecurringParameters

val recurringParameters = GooglePayRecurringParameters(
    immediateTotalPrice = "25.00",
    managementUrl = "https://merchant.example.com/subscriptions",
    billingAgreement = "Subscription auto-renews until cancelled.",
    // Optional free-trial / introductory pricing
    introductoryPeriodInfo = GooglePayIntroductoryPeriodInfo(
        introductoryPeriodEndDateTime = "2026-10-01T08:00:00Z",
        label = "7 Day Free Trial",
        totalPrice = "0.00",
    ),
    recurrenceItems = listOf(
        GooglePayRecurrencePeriodItem(
            label = "Premium Plan Monthly Subscription",
            price = "25.00",
            priceStatus = GooglePayPriceStatus.FINAL,
            recurrencePeriod = GooglePayRecurrencePeriod.MONTH,
            recurrencePeriodCount = 1,
            billingInitialDateTime = "2026-10-01T08:00:00Z",
            // billingFinalDateTime = null  -> open-ended subscription
        ),
    ),
)

val googlePayConfiguration = GooglePayConfiguration.Builder()
    .setEnvironment(GooglePayEnvironment.TEST)
    .setTransactionCountryCode("GB")
    .setMerchantName("My Store")
    .setRecurringParameters(recurringParameters)
    .build()

val judo = Judo.Builder(PaymentWidgetType.GOOGLE_PAY)
    .setJudoId("<JUDO_ID>")
    .setAuthorization(authorization)
    .setAmount(amount)
    .setReference(reference)
    .setIsSandboxed(true)
    .setGooglePayConfiguration(googlePayConfiguration)
    // First charge taken now, alongside mandate setup:
    .setInitialRecurringPayment(true)
    .build()

// Launch as usual — the MIT descriptor rides along on the Judo object:
private val googlePayLauncher =
    registerForActivityResult(JudoActivityResultContracts.GooglePay()) { onJudoResult(it) }

googlePayLauncher.launch(judo)

Judopay acts as a pass-through service, whereby we supply the data needed by Google Pay™ for them to return a device / merchant specific token that can be used for MIT transactions.

For a full description on all the object properties in the Google Pay™ recurring payments flow, see the Google Pay™ Documentation.

Deferred Payments

To trigger an initial transaction that allows you to set up a Google Pay™ deferred payment token for future Merchant Initiated Transactions (MIT):

The MIT parameters are attached to GooglePayConfiguration via setDeferredParameters(...) (GooglePayDeferredParameters)

Set the first-charge-now flag: Judo.Builder.setInitialRecurringPayment(true)

Build the Judo object with PaymentWidgetType.GOOGLE_PAY (or PRE_AUTH_GOOGLE_PAY) and start the SDK activity:

import com.judopay.judokit.android.Judo
import com.judopay.judokit.android.model.GooglePayConfiguration
import com.judopay.judokit.android.model.PaymentWidgetType
import com.judopay.judokit.android.model.googlepay.GooglePayDeferredParameters
import com.judopay.judokit.android.model.googlepay.GooglePayEnvironment
import com.judopay.judokit.android.model.googlepay.GooglePayPriceStatus

val deferredParameters = GooglePayDeferredParameters(
    // Nothing charged today:
    immediateTotalPrice = "0.00",
    // Date the single future charge is taken:
    billingDateTime = "2027-01-01T08:00:00Z",
    priceStatus = GooglePayPriceStatus.FINAL,
    price = "200.00",
    label = "Hotel Room Reservation",
    managementUrl = "https://merchant.example.com/bookings",
    billingAgreement = "Your card will be charged on the billing date shown.",
)

val googlePayConfiguration = GooglePayConfiguration.Builder()
    .setEnvironment(GooglePayEnvironment.TEST)
    .setTransactionCountryCode("GB")
    .setMerchantName("My Store")
    .setDeferredParameters(deferredParameters)
    .build()

val judo = Judo.Builder(PaymentWidgetType.GOOGLE_PAY)
    .setJudoId("<JUDO_ID>")
    .setAuthorization(authorization)
    .setAmount(amount)
    .setReference(reference)
    .setIsSandboxed(true)
    .setGooglePayConfiguration(googlePayConfiguration)
    .build()

private val googlePayLauncher =
    registerForActivityResult(JudoActivityResultContracts.GooglePay()) { onJudoResult(it) }

googlePayLauncher.launch(judo)

Judopay acts as a pass-through service, whereby we supply the data needed by Google Pay™ for them to return a device / merchant specific token that can be used for MIT transactions.

For a full description on all the object properties in the Google Pay™ deferred payments flow, see the Google Pay™ Documentation.

3D Secure 2 for Android

JudoKit-Android is enabled for 3D Secure 2 (EMV 3DS).

3D Secure 2 is available on JudoKit Android version 3.0.0 or higher, and is available on github.

Using the Pre-Built UI Card Entry Component

The easiest way to integrate 3D Secure is to use the pre-built UI component within JudoKit, as this handles the 3D Secure flow for you.

Using a 3D Secure Enabled credential*, follow the steps for Making a Transaction.

*We recommend using billingAddress and emailAddress fields for 3D Secure 2 transactions.

You can provide billingAddress and emailAddress in two ways: Add and populate billingAddress and emailAddress to the payment configuration object:

val uiConfiguration = UiConfiguration.Builder()
            //...
            // sets whether 3DS 2.0 UI billing information screen should be presented to the user
            .setShouldAskForBillingInformation(false)
            .build()

// in case you don't want to present billing info screen to the user, you can set the address instead
val address = Address.Builder()
                    .setLine1("My house")
                    .setLine2("My street")
                    .setTown("My town")
                    .setPostCode("TR14 8PA")
                    .setCountryCode("826")
                    .setBillingCountry("826")
                    .build()

val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)
            //...
            .setUiConfiguration(uiConfiguration)

            // sets the value for challenge request indicator,
            // possible values:
            // ChallengeRequestIndicator.NO_PREFERENCE
            // ChallengeRequestIndicator.NO_CHALLENGE
            // ChallengeRequestIndicator.CHALLENGE_PREFERRED
            // ChallengeRequestIndicator.CHALLENGE_AS_MANDATE
            .setChallengeRequestIndicator(ChallengeRequestIndicator.NO_PREFERENCE)

            // sets the value for SCA exemption,
            // possible values:
            // ScaExemption.LOW_VALUE
            // ScaExemption.SECURE_CORPORATE
            // ScaExemption.TRUSTED_BENEFICIARY
            // ScaExemption.TRANSACTION_RISK_ANALYSIS
            .setScaExemption(ScaExemption.LOW_VALUE)

            // email address
            .setEmailAddress("[email protected]")

            // sets the maximum timeout for 3DS 2.0 transactions in minutes,
            // always use 2 characters when setting the timeout
            .setThreeDSTwoMaxTimeout(30)

            // sets phone number country code
            .setPhoneCountryCode("44")

            // phone number
            .setMobileNumber("11223344556677")

            // 
            .setAddress(address)
            
            // ...
            .build()

Or, to request this information from your customer:

Enable the billingAddress and emailAddress fields to appear in the UI: .setShouldAskForBillingInformation(true)

Using Token Payments with 3D Secure 2

Using a 3D Secure Enabled credential*, follow the steps for Token Payments.

Make sure your account has 3D Secure 2 API credentials enabled. Contact Customer Support to set this up.

Adding Payment Methods

Configuring Google Pay™ for Android

Prerequisites

You have set up your Google Pay™ payments profile.

For more details, see Create a Payments Profile.

You have imported the following models:

import com.judopay.judokit.android.model.googlepay.GooglePayAddressFormat import com.judopay.judokit.android.model.googlepay.GooglePayBillingAddressParameters import com.judopay.judokit.android.model.GooglePayConfiguration import com.judopay.judokit.android.model.googlepay.GooglePayEnvironment import com.judopay.judokit.android.model.googlepay.GooglePayShippingAddressParameters

Creating the Google Pay™ Configuration

To create the Google Pay™ configuration:

Set the required properties using the prerequisite imported models.

Set some additional optional properties to customise Google Pay™:

val billingAddressParams = GooglePayBillingAddressParameters( format = GooglePayAddressFormat.MIN, phoneNumberRequired = true ) val shippingAddressParams = GooglePayShippingAddressParameters( phoneNumberRequired = true ) val googlePayConfiguration = GooglePayConfiguration.Builder() .setTransactionCountryCode("GB") .setEnvironment(GooglePayEnvironment.TEST) .setIsEmailRequired(true) .setIsBillingAddressRequired(true) .setBillingAddressParameters(billingAddressParams) .setIsShippingAddressRequired(true) .setShippingAddressParameters(shippingAddressParams) .build()

Field	Description
setTransactionCountryCode Required	Sets the transaction ISO-3166 country code.
setEnvironment Required	Sets the Google Pay™ environment to either: TEST PRODUCTION In order to go-live you will need to have set up your Google Pay™ API merchant live account.
setIsEmailRequired Optional	Sets the option for the consumer to provide their email address.
setIsBillingAddressRequired Optional	Sets the option for the consumer to provide their billing address.
setBillingAddressParameters Optional	Sets the billing address format.
SetIsShippingAddressRequired Optional	Sets the option for the consumer to provide their shipping information.
setShippingAddressParameters Optional	Sets the shipping address format.

Although setting the billing and shipping parameters is optional, they must be provided if the billing and shipping requirements are set to true.

Making a Google Pay™ Transaction

Prerequisite

You have set up the GooglePayConfiguration.

To make a Google Pay™ transaction:

Add the setGooglePayConfiguration method to the Judo builder

Set the PaymentWidgetType to:

GOOGLE_PAY

Start the Judo activity:

val judo = Judo.Builder(PaymentWidgetType.GOOGLE_PAY) ... .setGooglePayConfiguration(googlePayConfiguration) .build() val intent = Intent(this, JudoActivity::class.java); intent.putExtra(JUDO_OPTIONS, judo); startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE);

To make a Google Pay™ pre-auth request:

Add the setGooglePayConfiguration method to the Judo builder

Set the PaymentWidgetType to:

PRE_AUTH_GOOGLE_PAY

Start the Judo activity:

val judo = Judo.Builder(PaymentWidgetType.PRE_AUTH_GOOGLE_PAY) ... .setGooglePayConfiguration(googlePayConfiguration) .build() val intent = Intent(this, JudoActivity::class.java); intent.putExtra(JUDO_OPTIONS, judo); startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE);

Testing Android Mobile Card Transactions

Follow our suggested guidelines to simulate both positive / happy path scenarios, and negative scenarios in the sandbox environment to test your integration is working correctly. This will give you confidence for when your integration goes live.

See, Testing your Android SDK and generate:

Successful payments

Declined payments

Unexpected errors

Enable Google Pay™ on your Mobile App

You will need to have your app approved by Google prior to using Google Pay™ in production.

Ensure you have tested Google Pay™ on your mobile app. See, Testing Google Pay™ Wallet - via Mobile SDK.

Ensure your Android Application Package is enabled for sandbox testing. This is to permit the Google Pay™ Support Team to run their review tests.

Send your Android Application Package to the Google Pay™ Support Team so they can review your app and assist you with any of the Terms and Conditions that need to be agreed.

The Google Pay™ Support Team will enable your app with production access to Google Pay™, once their review has been successfully completed.

You will then be able to accept Google Pay™ transactions from your mobile app.