Judopay Documentation

Android

Prerequisites

  • You have set up your Judopay account.

  • You have the latest version of the Android SDK.

    For more details, see [→Android Integration].

Android Integration with Judopay

Tip

For Mobile apps, it is recommended not to make a transaction from the app, as the Token and Secret could become compromised. Use the server to make the transaction. Create a Register Card app and enable the Register Card Transactions permission.

Integration Requirements:

  • Android Studio 2.2 or higher

  • Android SDK Build Tools 25.0.2

  • Your app targets Android API version 16 Jelly Bean or higher

  • Latest Android Support Repository

  • Latest Android Support Library

  • Install using Android Studio

  • No need to clone a repository

The Mobile SDK is available for Android as a Gradle dependency. 

 

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:android-sdk version

An example of how your build.gradle might look:

android {
    ...
}

dependencies {
    ...
    implementation 'com.judopay:android-sdk:9.0.0'
    ...
}
  1. Add the Judopay Maven Repository Package:

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

Tip

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

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

import com.judopay.Judo 1


import com.judopay.model.Amount 2
import com.judopay.model.Reference
import com.judopay.model.PaymentWidgetType


import com.judopay.PAYMENT_CANCELLED 3
import com.judopay.PAYMENT_ERROR
import com.judopay.PAYMENT_SUCCESS


import com.judopay.JudoActivity 4

1

Judo is the class used to build the payment flow.

2

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

PaymentWidgetType allows for multiple payment types:

  • Card

  • Google Pay™ Apple Pay™

  • PayByBankApp

  • iDeal

to be selected and displayed.

3

Identifies the transaction result:

  • PAYMENT_SUCCESS

  • PAYMENT_ERROR

  • PAYMENT_CANCELLED

4

JudoActivity is the method parameter when calling startActivityForResult.

Building the Judo Object

To set up the transaction amount:

1. In the Amount object provide the:

  • Amount value

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

  • Consumer reference string

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

To set up the Judo configuration:

1. Set the following required parameters:

  • The token and secret values

  • Set the SDK to run in sandbox mode

  • Set the following objects:

    • Judo ID

    • Amount

    • Reference

  • Set the PaymentWidgetType parameter to select the Judo operation:

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

Field

Description

CARD_PAYMENT

Card Payment

PRE_AUTH_CARD_PAYMENT

Card PreAuth

CREATE_CARD_TOKEN

Register Card

SAVE_CARD

Save Card

CHECK_CARD

Check Card

PaymentWidgetType.PAYMENT_METHODS

Payment Method Selection

PaymentWidgetType.PRE_AUTH_PAYMENT_METHODS

PreAuth Method Selection

PaymentWidgetType.GOOGLE_PAY

Google Pay (Payment)

PaymentWidgetType.PRE_AUTH_GOOGLE_PAY

Google Pay (PreAuth)

 

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

Note

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.JUDO_OPTIONS, judo);
startActivityForResult(intent, PAYMENT_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 == PAYMENT_REQUEST_CODE) {
        when (resultCode) {

            PAYMENT_CANCELLED -> toast("User cancelled the payment.")

            PAYMENT_SUCCESS -> {
                val receipt = data?.getParcelableExtra<Receipt>(JUDO_RECEIPT)
                // Handle response
            }

            PAYMENT_ERROR -> {
                val error = data?.getParcelableExtra<ApiError>(JUDO_ERROR)
                // Handle error
            }
        }
    }
}

 

Check the request code from the onActivityResult and see if it matches with the PAYMENT_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:

    SERVER_TO_SERVER_PAYMENT_METHODS:

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 transaction using a stored card token.

Steps:

  1. Use the TokenPayment or TokenPreAuth endpoints

  2. Create a function

  3. Create the Card Token and Secret

  4. Send a Json Request

  5. Handle the Response

Billing Address | primary account details | CV2 are optional fields.

yourConsumerReference | yourPaymentReference | amount | currency | judo ID are mandatory fields.

Making a Token Payment

To make a token payment or PreAuth token payment:

  1. Create the api service via JudoApiServiceFactory:

val service = JudoApiServiceFactory.createApiService(this, judo)
  1. Call the tokenPayment or preAuthTokenPayment

    This is a TokenRequest object that requires the card token and optional security code:

service.tokenPayment(judo.toTokenPayment(cardToken, "452"))
service.preAuthTokenPayment(judo.toTokenPayment(cardToken, "452"))
  1. Handle the callback:

service.tokenPayment(getJudo(judo).toTokenPayment(cardToken, "452"))
                   .enqueue(object: Callback<JudoApiCallResult<Receipt>>{
                    override fun onFailure(call: Call<JudoApiCallResult<Receipt>>, t: Throwable) {
                        TODO("Not yet implemented")
                    }

                    override fun onResponse(
                        call: Call<JudoApiCallResult<Receipt>>,
                        response: Response<JudoApiCallResult<Receipt>>
                    ) {
                          when (val result = response.body()?.toJudoPaymentResult()) {
                            is JudoPaymentResult.Error -> //handle error result
                            is JudoPaymentResult.Success -> //handle success result
                          }
                    }
                })

Testing Android Mobile Transactions

To test Android transactions in the sandbox environment:

  1. Add the sandbox token and secret to your app’s main Activity class

  2. Ensure the SDK is configured for the sandbox environment

  3. Use the test cards provided in the Judopay Portal: Tools > Generating transactionsNavigating the Judopay Portal

Caution

Ensure you are using a consumerReference for each request.

Customising the Payment Experience

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

Configuring the UI

You have flexibility on how the payment experience looks to the consumer.

The JudoUIConfiguration 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

To create the UIConfiguration object:

import com.judopay.model.UIConfiguration

val uiConfiguration = UIConfiguration.Builder()
                        .setAVSEnabled(true)
                        .setShouldDisplayAmount(true)
                        .setShouldPaymentMethodsVerifySecurityCode(true)
                        .setShouldPaymentButtonDisplayAmount(true)
                        .build()

1. Call setUIConfiguration on the Judo builder

2. Pass the uiConfiguration object:

val judo = Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
            ...
            .setUIConfiguration(uiConfiguration)
            .build()

Setting the Primary Account Details

Note

To set the primary account details when using an alternative payment method, see Alternative Payment Method Configuration.

You can also set the primary account details to be sent with the transaction.

To set the primary account details:

1. Call the setPrimaryAccountDetails on the Judo builder:

val primaryAccountDetails = PrimaryAccountDetails.Builder()
                              .setName("example-name")
                              .setAccountNumber("example-account-number")
                              .setDataOfBirth("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:

  1. Set the setSupportedCardNetworks on the Judo builder with an array of CardNetwork values.

For the purpose of this exercise, Visa and MasterCard are selected as the supported card networks:

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

Discover

DISCOVER

Diners Club

DINERS_CLUB

Other

OTHER

Setting a Card Address

Note

To set the card address when using an alternative payment method, see Alternative Payment Method Configuration.

To send additional card address details with the transaction:

1. Add the setAddress call on the Judo builder object:

al address = Address.Builder()
                    .setLine1("line1")
                    .setLine2("line2")
                    .setLine3("line3")
                    .setPostCode("my-postcode")
                    .setTown("town")
                    .setCountryCode("GB")
                    .build()

Tip

All the above properties are optional, so set only the ones you need.

2. Call setAddress on the Judo builder:

val judo = Judo.Builder(PaymentWidgetType.CARD_PAYMENT)
                    ...
                    .setAddress(address)
                    .build()

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:

  1. Call the setPaymentMethods on the Judo builder

  2. 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()

Note

The order you add the payment methods into the array, is the order they will be displayed on screen.

Payments Widget

To set up the Payments Widget for Android:

1. Change the PaymentWidgetType to either:

  • PAYMENT_METHODS or, 

  • PRE_AUTH_PAYMENT_METHODS

For example:

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

2. Start the Judo Activity:

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

Alternative Payment Methods

PayByBankApp

PayByBankApp enables consumers to use bank transfers to easily pay for goods and services online.

For more details on using the PayByBankApp as an alternative payment method, see:

Configuring the PayByBankApp Button

To add the Pay by Bank button:

1. Insert the button in the layout file:

<com.judokit.android.ui.common.PayByBankButton
        android:id="@+id/payByBankButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />

2. Set OnClickListener to the PayByBankApp button

  • The JudoActivity will start and pass the result to merchant

payByBankButton.setOnClickListener {
            val intent = Intent(this, JudoActivity::class.java)
            intent.putExtra(JUDO_OPTIONS, judo)
            startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
        }

3. Enable the PayByBankApp in the Payment Selector Screen:

  • Build the Judo configuration object:

    • Set the payment widget type to:

      • PaymentWidgetType.PAYMENT_METHODS

    • Set currency:

      • GBP

val amount = Amount.Builder()
            .setAmount("1")
            .setCurrency(Currency.GBP)
            .build()
            
Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

4. Start JudoActivity with the JudoConfiguration object:

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

Caution

For the PayByBankApp button to appear in the Payments Widget, a banking app must already be installed.

The PayByBankApp Button is displayed:

Screenshot_1592899438.png

iDEAL

iDEAL enables consumers to easily pay online for goods and services in the Netherlands.

For more details using iDEAL as an alternative payment method, see:

Displaying iDEAL as a Payment Method

To add iDEAL support to your Payments Widget, set:

  1. The currency code to EUR (Euro)

  2. The JudoId

The judoId parameter can be set by calling setJudoId on 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.

Android Styles and Themes

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, follow the Android Developer Guide here.