Android

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

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

  1. Navigate to your build.gradle file

  2. 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'
    ...
}

 

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

 

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

      to be selected and displayed.

  • Identifies the transaction result:

    • PAYMENT_SUCCESS

    • PAYMENT_ERROR

    • PAYMENT_CANCELLED

  • The JudoActivity class is used to start a payment intent.

 

Building the Judo Object

To set up the transaction amount:

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

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

 

To set up the transaction reference:

  1. In the Reference object provide the ConsumerReference string:

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

 

To set up the Judo configuration:

  1. Set the following required parameters:

    1. The token and secret values, OR Create the authorisation object:

    2. Set the SDK to run in sandbox mode

  1. Set the following objects:

    1. Judo ID

    2. Authorisation object (if using this method)

JudoId format = 100100100

  1. Amount

  2. Reference

 

  1. Create the authorisation object:

val authorization = PaymentSessionAuthorization.Builder()
       .setPaymentSession(paymentSession)
       .setApiToken(token)
       .build()
  1. 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.

REGISTER_CARD

Register Card

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:

  1. Create an Intent to pass the JudoActivity class

  2. Add the Judo object to the Intent:

    1. Call putExtra

    2. Assign it to the JUDO_OPTIONS key

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

  1. 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);

 

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

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

    in the Judo object.

For more information, see the Android Sample App.

 

3D Secure 2 for Android

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

 

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

 

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:

  1. 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")
                    .setLine3("My area")
                    .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()

 

  1. 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 making Token Payments.

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

 

Customising your Integration

You can customise the payment experience for the consumer by configuring the following UI behaviour properties in the UiConfiguration object:

 

Adding Payment Methods

 

 

Testing Android Mobile Card Transactions

Follow our Testing your Android SDK Integration test scenarios, to test your mobile app card transactions 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.

 

  1. Ensure you have tested Google Pay™ on your mobile app.

    See, Testing Google Pay™ Wallet - via Mobile SDK.

  2. Ensure your Android Application Package is enabled for sandbox testing.

    This is to permit the Google Pay™ Support Team to run their review tests.

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

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