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:
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
1val uiConfiguration = UiConfiguration.Builder()2//...3// sets whether 3DS 2.0 UI billing information screen should be presented to the user4.setShouldAskForBillingInformation(false)5.build()67// in case you don't want to present billing info screen to the user, you can set the address instead8val address = Address.Builder()9.setLine1("My house")10.setLine2("My street")11.setTown("My town")12.setPostCode("TR14 8PA")13.setCountryCode("826")14.setBillingCountry("826")15.build()1617val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)18//...19.setUiConfiguration(uiConfiguration)2021// sets the value for challenge request indicator,22// possible values:23// ChallengeRequestIndicator.NO_PREFERENCE24// ChallengeRequestIndicator.NO_CHALLENGE25// ChallengeRequestIndicator.CHALLENGE_PREFERRED26// ChallengeRequestIndicator.CHALLENGE_AS_MANDATE27.setChallengeRequestIndicator(ChallengeRequestIndicator.NO_PREFERENCE)2829// sets the value for SCA exemption,30// possible values:31// ScaExemption.LOW_VALUE32// ScaExemption.SECURE_CORPORATE33// ScaExemption.TRUSTED_BENEFICIARY34// ScaExemption.TRANSACTION_RISK_ANALYSIS35.setScaExemption(ScaExemption.LOW_VALUE)3637// email address38.setEmailAddress("[email protected]")3940// sets the maximum timeout for 3DS 2.0 transactions in minutes,41// always use 2 characters when setting the timeout42.setThreeDSTwoMaxTimeout(30)4344// sets phone number country code45.setPhoneCountryCode("44")4647// phone number48.setMobileNumber("11223344556677")4950// 51.setAddress(address)5253// ...54.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
1import com.judopay.judokit.android.UIConfiguration
23val uiConfiguration = UIConfiguration.Builder()4.setAvsEnabled(true)5.setShouldPaymentMethodsDisplayAmount(true)6.setShouldPaymentMethodsVerifySecurityCode(true)7.setShouldPaymentButtonDisplayAmount(true)8.setShouldAskForCardholderName(true)9.setShouldAskForBillingInformation(true)10.build()1112//Call setUIConfiguration on the Judo builder13//Pass the uiConfiguration object:1415val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)16...17.setUIConfiguration(uiConfiguration)18.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.
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:
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.
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.
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.