Android

Integrating Android with Judopay
Prerequisites
You have set up your Judopay account.
Sign up for your sandbox account, to receive access to your Judopay dashboard and the sandbox environment.
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 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™
iDEAL
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:
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.
﻿
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 Card Entry UI
The easiest way to integrate 3D Secure is to use the UI 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:
Card Entry Example
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()
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@me.com")

            // 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﻿.
﻿
﻿
Customising your Integration
You can customise the payment experience for the consumer by configuring the following UI behaviour properties in the UIConfiguration object:
UI Configuration
You have flexibility on how the payment experience looks to the consumer.
The UIConfiguration object allows you to:
Enable | disable the Address Verification Service 
Show | hide the amount in the Payments Widget
Enable | disable consumers entering the CV2 code
Show | hide the amount in the payment button
Enable | disable asking the consumer for their cardholder name
Enable | disable asking the consumer for their billing information
To create the UIConfiguration object:
UI Configuration Object
import com.judopay.judokit.android.UIConfiguration

val uiConfiguration = UIConfiguration.Builder()
           .setAvsEnabled(true)
           .setShouldPaymentMethodsDisplayAmount(true)
           .setShouldPaymentMethodsVerifySecurityCode(true)
           .setShouldPaymentButtonDisplayAmount(true)
           .setShouldAskForCardholderName(true)
           .setShouldAskForBillingInformation(true)
           .build()

//Call setUIConfiguration on the Judo builder
//Pass the uiConfiguration object:

val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
    ...
        .setUIConfiguration(uiConfiguration)
        .build()
import com.judopay.judokit.android.UIConfiguration

val uiConfiguration = UIConfiguration.Builder()
           .setAvsEnabled(true)
           .setShouldPaymentMethodsDisplayAmount(true)
           .setShouldPaymentMethodsVerifySecurityCode(true)
           .setShouldPaymentButtonDisplayAmount(true)
           .setShouldAskForCardholderName(true)
           .setShouldAskForBillingInformation(true)
           .build()

//Call setUIConfiguration on the Judo builder
//Pass the uiConfiguration object:

val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
    ...
        .setUIConfiguration(uiConfiguration)
        .build()
﻿
﻿
 Setting up an Incremental Authorisation
The incremental authorisation feature allows you to increment the value of your original preAuth for scenarios where you need to charge your customer a higher total amount.
By incrementing the preAuth value, you will be able to capture the total amount that you wish to charge your customer when you are ready.
The allowIncrement flag allows you to set up your initial preAuth so that it can be incremented by an additional amount.
This feature is only available with a limited set of processors - please check with your account manager before you use this feature.
allowIncrement is part of the main Judo config object, and can be set by the setAllowIncrement function.
If present = it is automatically applied for preAuth requests.
If no value is provided = then false is set by default.
Example:
Judo.Builder(PaymentWidgetType.PRE_AUTH)
 (…)
 .setAllowIncrement(true)
 .build()
﻿
Setting the Primary Account Details
It is mandatory for merchants who have an MCC code of 6012 to submit additional Information about the primary account holder in primaryAccountDetails for payment pre-authorisation.
To set the primary account details when using an alternative payment method, see  Adding Payment Methods﻿.
You can also set the primary account details to be sent with the transaction.
To set the primary account details:
Call the setPrimaryAccountDetails on the Judo builder:
Setting Primary Account Details
val primaryAccountDetails = PrimaryAccountDetails.Builder()
                              .setName("example-name")
                              .setAccountNumber("example-account-number")
                              .setDateOfBirth("example-date")
                              .setPostCode("example-postcode")
                              .build()

val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)
            ...
            .setPrimaryAccountDetails(primaryAccountDetails)
            .build()
val primaryAccountDetails = PrimaryAccountDetails.Builder()
                              .setName("example-name")
                              .setAccountNumber("example-account-number")
                              .setDateOfBirth("example-date")
                              .setPostCode("example-postcode")
                              .build()

val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)
            ...
            .setPrimaryAccountDetails(primaryAccountDetails)
            .build()
﻿
 
Changing the Default Supported Card Networks
You can select the card networks you want to support. 
To select the supported card networks:
Set the setSupportedCardNetworks on the Judo builder with an array of CardNetwork values.
val networks = arrayOf(CardNetwork.VISA, CardNetwork.MASTERCARD)

val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)
 ...
 .setSupportedCardNetworks(networks)
 .build()
Card Network Options:
Card Network Name
Value
Visa
VISA
MasterCard
MASTERCARD
AMEX
AMEX
China Union Pay
CHINA_UNION_PAY
JCB
JCB
Maestro
MAESTRO
Diners Club International
DINERS_CLUB
Discover
DISCOVER
Other
OTHER
﻿
Changing the Default Payment Methods
By default, all payment methods are displayed in the Payments Widget (as long as the required parameters are set).
However, you can select the payment methods you want to support.
To select the supported payment methods:
Call the setPaymentMethods on the Judo builder
Pass an array of PaymentMethod enum values:
val paymentMethods = arrayOf(
 PaymentMethod.CARD,
 PaymentMethod.GOOGLE_PAY,
 PaymentMethod.IDEAL
)

val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)
 ...
 .setPaymentMethods(paymentMethods)
 .build()
The order you add the payment methods to the array is the order they will be displayed on screen.
﻿
Payments Widget
To set up the Payments Widget for Android:
Change the PaymentWidgetType to either:
PAYMENT_METHODS
or, 
PRE_AUTH_PAYMENT_METHODS
For example:
Setting up the Payments Widget
val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
            .setApiToken("my-token")
            .setApiSecret("my-secret")
            .setIsSandboxed(true)
            .setJudoId("my-judo-id")
            .setAmount(amount)
            .setReference(reference)
            .setGooglePayConfiguration(googlePayConfiguration)
            .build()

//Start the Judo Activity:

val intent = Intent(this, JudoActivity::class.java);
intent.putExtra(JUDO_OPTIONS, judo);
startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE);
val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
            .setApiToken("my-token")
            .setApiSecret("my-secret")
            .setIsSandboxed(true)
            .setJudoId("my-judo-id")
            .setAmount(amount)
            .setReference(reference)
            .setGooglePayConfiguration(googlePayConfiguration)
            .build()

//Start the Judo Activity:

val intent = Intent(this, JudoActivity::class.java);
intent.putExtra(JUDO_OPTIONS, judo);
startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE);
﻿
 
Android Styles and Themes
Styling
You have the flexibility of creating your own styling and colour values:
Override the styles.xml properties
to provide your own styling
Override the colors.xml properties
to provide your own colour values
For a more detailed explanation on:
Styles and Themes: See the Android Developer Guide.
Brand Guidelines: See the Google Pay™ Brand Guidelines.
﻿
﻿
Adding Payment Methods
Integrating Google Pay for Android
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);
Integrating iDEAL for Android
To add iDEAL support to your Payments Widget, set:
The currency code to EUR (Euro)
The JudoId
The judoIdparameter can be set by calling setJudoIdon the Judo builder.
An example of a valid iDEAL configuration:
 val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS) 
... 
.setJudoId("my-judo-id") 
.setCurrency("EUR") 
.build()
Once the currency and judoId are set, iDEAL will be available as a payment method in the Payments Widget.
 
﻿
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.
Updated 06 Aug 2024
Did this page help you?
Mobile SDKs
iOS
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
Card Network Name	Value
Visa	VISA
MasterCard	MASTERCARD
AMEX	AMEX
China Union Pay	CHINA_UNION_PAY
JCB	JCB
Maestro	MAESTRO
Diners Club International	DINERS_CLUB
Discover	DISCOVER
Other	OTHER
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.