--- title: Android slug: android docTags: createdAt: 2024-05-20T15:25:03.869Z --- # Integrating Android with Judopay ## Prerequisites - You have set up your Judopay account. - Sign up for your [sandbox account](https://www.judopay.com/apply-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](docId\:S_8hOAMytkgY13t0P657-). - You have the latest version of the Android SDK. :::hint{type="info"} For Mobile apps, we recommend using **[payment session authentication](docId\:ylKW5coh5NQnfQ3j_Wjk2)**. ::: ## 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](https://developer.android.com/google/play/requirements/target-sdk). - 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](https://github.com/Judopay/JudoKit-Android/releases). An example of how your **build.gradle **might look: :::BlockQuote android \{ ... } dependencies \{ ... implementation 'com.judopay\:judokit-android:4.0.1' ... } ::: 3\. Ensure the Maven Central Repository has been added: :::BlockQuote allprojects \{ repositories \{ mavenCentral() } } ::: :::hint{type="info"} See Judopay's JudoKit for Android on **[Github](https://github.com/Judopay/JudoKit-Android)**. ::: *** ## 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: :::BlockQuote 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 1. In the **Amount** object provide the **Amount **value and **Currency **type: :::BlockQuote val amount = Amount.Builder() .setAmount("150.50") .setCurrency(Currency.GBP) .build() ::: ### Set up the Transaction Reference 1. In the **Reference** object provide the **ConsumerReference **string: :::BlockQuote val reference = Reference.Builder() .setConsumerReference('my-consumer-reference') .build() ::: ### Set up the Judo Configuration 1. Set the following **required** parameters: 1. The token and secret values, **OR **create the authorisation object (Step 3 below). 2. Set the SDK to run in **sandbox** mode 2. Set the following objects: 1. Judo ID 1. **JudoId format = 100100100** 2. Authorisation object (if using this method) 3. Amount 4. Reference 3. Create the authorisation object: :::hint{type="warning"} Merchants operating in specific money movement and financial services categories, as defined by the card schemes **must include** additional data in the [payment session](docId\:ylKW5coh5NQnfQ3j_Wjk2). For more information, see [Account Funding Transactions](docId:5ol_pTSGBHVGKwJwD0gHg). ::: :::BlockQuote val authorization = PaymentSessionAuthorization.Builder() .setPaymentSession(paymentSession) .setApiToken(token) .build() ::: 4\. Set the authorisation object when invoking Judo builder: :::BlockQuote 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: 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 :::hint{type="info"} 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: :::BlockQuote 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: :::BlockQuote 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\(JUDO\_RESULT) // Handle response } PAYMENT\_ERROR -> \{ val error = data?.getParcelableExtra\(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: :::BlockQuote 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](docId\:it3YrNIhEgskEtQTsxGi3) and replace the `PaymentWidgetType` with: - PaymentWidgetType.TOKEN\_PRE\_AUTH or - PaymentWidgetType.TOKEN\_PAYMENT For more information on token payments, see the [Android Sample App](https://github.com/Judopay/JudoKit-Android/tree/master/judokit-android-examples/src/main/java/com/judokit/android/examples/feature/tokenpayments). *** ## Setting up Recurring Payments Make sure you are using: - Android SDK **Version 7.2.0** (or higher) :::hint{type="warning"} 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: :::CodeblockTabs Recurring Payments Example ```java 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("") .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](https://developers.google.com/pay/api/android/reference/request-objects#RecurringTransactionInfo). *** ### 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: :::CodeblockTabs Deferred Payment Example ```java 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("") .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](https://developers.google.com/pay/api/android/reference/request-objects#DeferredTransactionInfo). *** ## 3D Secure 2 for Android **JudoKit-Android **is enabled for 3D Secure 2 (EMV 3DS). :::hint{type="info"} 3D Secure 2 is available on JudoKit Android **version 3.0.0 **or higher, and is available on [github](https://github.com/Judopay/JudoKit-Android/releases/tag/v3.0.0). ::: ### 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](docId\:it3YrNIhEgskEtQTsxGi3). :::hint{type="warning"} **\***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**: :::CodeblockTabs Card Entry Example ```java 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](docId\:it3YrNIhEgskEtQTsxGi3). :::hint{type="warning"} Make sure your account has **3D Secure 2 API credentials **enabled. Contact ​Customer Support​​ to set this up. ::: *** ## Adding Payment Methods ::::ExpandableHeading ### 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.](https://support.google.com/googleplay/android-developer/answer/7161426?hl=en-GB) - You have imported the following models: :::BlockQuote 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: 1. Set the required properties using the prerequisite imported models. 2. Set some additional optional properties to customise Google Pay™: :::BlockQuote 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. | :::hint{type="warning"} 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: 1. Add the **setGooglePayConfiguration** method to the Judo builder 2. Set the PaymentWidgetType to: - GOOGLE\_PAY 3. Start the Judo activity: :::BlockQuote 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: 1. Add the **setGooglePayConfiguration** method to the Judo builder 2. Set the PaymentWidgetType to: - PRE\_AUTH\_GOOGLE\_PAY 3. Start the Judo activity: :::BlockQuote 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](docId\:VZB3q7wp2Hf0LJGdO8VnD) and generate: - Successful payments - Declined payments - Unexpected errors *** ## Enable Google Pay™ on your Mobile App :::hint{type="warning"} 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](docId\:PDWr34AvmT3iws1j8xtsQ). 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.