Developer Guide
Contact Us

Android

Adding the ReadyRemit SDK Package to Your Android Project

Suggest Edits

In this guide, you will learn how to integrate the ReadyRemit SDK into your Android app.

Step 1 - Prepare for the ReadyRemit SDK

  1. Make sure that your app's minimum Android API level is 26 or higher. This can be found in the build.gradle file. Depending on your setup this might be defined in the build.gradle file at the Module level or at the Project level.

    android {
    compileSdkVersion 33
    defaultConfig {
        ...
        minSdkVersion 26
      	targetSdkVersion 33
    }
  
    // Java and Kotlin versions compatibility
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = '1.8'
    }
}

  2. Add classpath dependencies to the build.gradle at the Project level.

    buildscript {
    ...
    ext {
        ...
        kotlinVersion = "1.7.20"
    }
  
    dependencies {
        ...
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
        classpath 'com.android.tools.build:gradle:7.4.2'
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
        jcenter()
        maven { url 'https://maven.google.com' }
        maven { url "https://jitpack.io" }
    }
}

🚧

Newer Gradle versions 8.0 or above.

if you are using a newer gradle structure of 8.0 or above, you should not add this segment of code.

allprojects {
    repositories {
        google()
        mavenCentral()
        jcenter()
        maven { url 'https://maven.google.com' }
        maven { url "https://jitpack.io" }
    }
}

instead open your settings.gradle and add the following:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
       	jcenter()
        maven { url 'https://maven.google.com' }
        maven { url "https://jitpack.io" }
    }
}

also in your gradle.properties add this line:

android.enableJetifier=true

  1. Add the following apply statements to the top of your build.gradle file at the Module level:
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-kapt'

Step 2 - Install the ReadyRemit SDK

  1. Download the readyremit.aar from the Releases page on Github
  2. Add the .aar file to the folder your_app_root/app/libs
  3. Add the path as a dependency to your app'sbuild.gradle file a the Module level:
dependencies {
    ...
    // ReadyRemit SDK
    implementation files('libs/readyremit.aar')
}
  1. Add missing third-party dependencies to your app's build.gradle file at the Module level:
dependencies {
    ...
    // ReadyRemit SDK
    implementation files('libs/readyremit.aar')

    // The following are required to run the SDK
    // please add the ones your project does not have
    // Core
    implementation "androidx.core:core-ktx:1.10.0"

    // UI
    implementation "androidx.appcompat:appcompat:1.6.1"
    implementation "com.google.android.material:material:1.9.0"

    // Navigation
    implementation "androidx.navigation:navigation-fragment-ktx:2.6.0"
    implementation "androidx.navigation:navigation-ui-ktx:2.6.0"
    implementation "androidx.navigation:navigation-compose:2.6.0"

    // Compose
    implementation platform("androidx.compose:compose-bom:2023.06.01")
    implementation "androidx.compose.compiler:compiler:1.3.2"
    implementation "androidx.compose.runtime:runtime:1.3.2"
    implementation "androidx.compose.material:material:1.3.2"
    implementation "androidx.compose.ui:ui-tooling"
    implementation "androidx.compose.ui:ui-tooling-preview"
    implementation "androidx.lifecycle:lifecycle-runtime-compose:2.6.0"

    implementation 'com.github.DImuthuUpe:AndroidPdfViewer:3.1.0-beta.1'

    // Kotlin
    implementation platform("org.jetbrains.kotlin:kotlin-bom:1.8.22")
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android"

    // OkHttp
    implementation "com.squareup.okhttp3:okhttp:4.11.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.11.0"

    // Profiler
    implementation "com.localebro:okhttpprofiler:1.0.8"

    // Retrofit
    implementation "com.squareup.retrofit2:retrofit:2.9.0"
    implementation "com.squareup.retrofit2:converter-gson:2.9.0"
    implementation "com.squareup.retrofit2:converter-moshi:2.9.0"

    // Moshi
    implementation "com.squareup.moshi:moshi:1.14.0"
    implementation "com.squareup.moshi:moshi-adapters:1.14.0"
    kapt "com.squareup.moshi:moshi-kotlin-codegen:1.14.0"

    // Dagger
    implementation "com.google.dagger:dagger:2.50"
    implementation "com.google.dagger:dagger-android:2.50"
    implementation "com.google.dagger:dagger-android-support:2.50"
    kapt "com.google.dagger:dagger-compiler:2.50"
    kapt "com.google.dagger:dagger-android-processor:2.50"

    // Mixpanel
    implementation "com.mixpanel.android:mixpanel-android:7.4.1"

    // Launch Darkly
    implementation "com.launchdarkly:launchdarkly-android-client-sdk:5.0.0"
}
  1. Add the buildFeatures and composeOptions blocks in your app’s build.gradle file at the Module level: 
android {
    ...
    // UI building features
    buildFeatures {
        dataBinding true
        viewBinding true
        buildConfig true
        compose true
    }
  
    // add composeOptions in order to support Jetpack Compose
    composeOptions {
        kotlinCompilerExtensionVersion '1.3.2'
    }
}

Step 3 - Install required Visa sensory branding libraries

  1. Download visa-sensory-branding-sdk from Github.
  2. Add the .aar file to the folder your_app_root/app/libs.
  3. Add the path as a dependency to your app's build.gradle file a the Module level:
dependencies {
    ...
    implementation files ('libs/visa-sensory-branding-2.0.aar') 
}

Step 4 - Initialize the SDK

SDK initialization needs to happen before it can be launched. Initialization can be done in your Application onCreate method, or in any activity, as long as you pass your Application object to it.
The ReadyRemit SDK initialization requires three parameters:

  • Environment: Choose between PRODUCTION and SANDBOX.
  • A callback to get the authentication token.
  • A callback to submit the transfer.
ReadyRemit.initialize(
    ReadyRemit.Config.Builder(application) // Application object returned by 'getApplication()' method
        .useEnvironment(Environment.SANDBOX) // Selected environment
        .useAuthProvider { callback -> requestReadyRemitAccessToken(callback) } // Your Access Token callback
        .useTransferSubmitProvider { request, callback -> submitReadyRemitTransfer(request, callback) } // Your Submit Transfer callback
       	.useDefaultTheme(R.style.ReadyRemit)
        .useLanguage("es") // Language code can also be specified in ReadyRemit.remitFrom() function.
        .build()
)

Step 5 - Retrieve an auth token and submit a transfer

The access token callback should return a ReadyRemitAuth object that includes the access token. The access should be obtained by your server (see Server side integration for more details) and provided to your app.

To request an Auth Token, use the following code.

private fun requestReadyRemitAccessToken(callback: ReadyRemitAuthCallback) {
    // On success
    callback.onAuthSucceeded(
        ReadyRemitAuth(
            // Access token from an API call to your backend, or from memory storage
            accessToken,
            "" // Empty String
        )
    )
      
    // On failure (error code should be returned from your server if the submission fails)
    callback.onAuthFailed()
}

The submit transfer callback operation performs a call to request the transfer. If successful, it will return a transfer id to your server.

To submit a transfer, use the following code.

private suspend fun submitReadyRemitTransfer(
    request: ReadyRemitTransferRequest,
    callback: ReadyRemitTransferCallback
) {
    // Call to your server to submit the transfer
    // Example: response = api.SubmitTransfer(request);
 
    // On success (transfer ID should be returned from your server)
    callback.onTransferSucceeded(transferId)
 
    // On failure (error code should be returned from your server if the submission fails)
    callback.onTransferFailed(errorCode)
}

❗️

SECURITY WARNING

We strongly recommend not storing the access token in any long-term storage. If obtained maliciously, this token can be used to view your user's confidential financial information.

Step 6 - Launch SDK

To launch the ReadyRemit SDK, use the following code. It should be triggered from an Activity typically inside a button's OnClick Listener.

/**
 * Launch ReadyRemitSDK
 *
 * @param1 "this" is the current Activity object.
 * @param2 "REQUEST_CODE" The request code to identify ReadyRemit Activy launching. It is an integer.
 * @param3 "theme" is your custom theme (R.style.sample_theme), you will see how to create one on the following section. .
 * @param4 "languageCode" is the locale code. It can include the region (for example: en-US, es-Mx).
 */
ReadyRemit.remitFrom(this, REQUEST_CODE, theme, languageCode)

(Optional) Style the ReadyRemit SDK

  1. In the root of your Android project create a new Values Resource File (ex: theme_readyremit.xml).
  2. Use the following code as a template and fill in any colors you'd like to override:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="Theme.ReadyRemit" parent="Theme.ReadyRemit.Light">
        <item name="rrmBackgroundColor">#F3F4F6</item>
        <item name="rrmForegroundColor">#FFFFFF</item>
        <item name="rrmButtonTextColor">#FFFFFF</item>
        <item name="rrmButtonColor">#743FC9</item>
        <item name="rrmDangerColor">#AA220F</item>
        <item name="rrmDangerLightColor">#F4E9E7</item>
        <item name="rrmDividerColor">#E2E2E2</item>
        <item name="rrmIconColor">#444444</item>
        <item name="rrmInputLineColor">#858585</item>
        <item name="rrmPrimaryColor">#934AE0</item>
        <item name="rrmPrimaryLightColor">#F3EDFB</item>
        <item name="rrmSuccessColor">#008761</item>
        <item name="rrmTextColor">#0E0F0C</item>
        <item name="rrmTextSecondaryColor">#454545</item>
    </style>
</resources>
  1. Navigate to the project's resource folder. The path should be something like: MyProject/app/src/main/res
  2. Ensure that there is a folder named values-night. If this folder doesn't exist, create it.
  3. Inside the values-night folder, create an XML file with the exact same name as the original theme used for the light mode.
  4. Open the project in Android Studio. In the res/values directory, you will find a directory for these themes. There will be one for light mode and one for dark mode (indicated by night tag).
  5. In the dark mode theme file, add the following structure:

🚧

Important

• Make sure to set the parent attribute to Theme.ReadyRemit.Dark.

• If you're only using the light mode in your application, you can copy the same colors from the theme used for the light mode. If you're using the dark mode, make the necessary color modifications here.

<?xml version="1.0" encoding="utf-8"?> 
<resources> 
    <style name="Theme.ReadyRemit" parent="Theme.ReadyRemit.Dark"> 
        <item name="rrmBackgroundColor">#111111</item> 
        <item name="rrmForegroundColor">#1F1F1F</item> 
        <item name="rrmButtonTextColor">#FFFFFF</item> 
        <item name="rrmButtonColor">#558CF4</item>
        <item name="rrmDangerColor">#AA220F</item> 
        <item name="rrmDangerLightColor">#201311</item> 
        <item name="rrmDividerColor">#313131</item> 
        <item name="rrmIconColor">#7E7E7E</item> 
        <item name="rrmInputLineColor">#505050</item> 
        <item name="rrmPrimaryColor">#558CF4</item> 
        <item name="rrmPrimaryLightColor">#83ACF7</item> 
        <item name="rrmSuccessColor">#008761</item> 
        <item name="rrmTextColor">#E3E3E3</item> 
        <item name="rrmTextSecondaryColor">#B0B0B0</item>
    </style>
</resources>
  1. Update the launch function to use the new theme. 
ReadyRemit.remitFrom(currentActivity, REQUEST_CODE, R.style.ReadyRemit, language)

(Optional) Closing ReadyRemitSDK

If you wish to gracefully close the ReadyRemitSDK at any point in your code, you can achieve this with the following method:

fun closeReadyRemitSDK() {  
    ReadyRemit.close()  
}

(Optional) Inactivity Detector

If you prefer to automatically close the ReadyRemitSDK when your users are inactive, you can use the following snippet. Place it in your activity where you launch the SDK.

import android.os.Bundle  
import androidx.appcompat.app.AppCompatActivity  
import com.yourcompany.ReadyRemitSDK

class YourActivity : AppCompatActivity() {
  
    private val REQUEST_CODE = 1 // Replace with your actual request code
    private val theme = "your_theme" // Replace with your actual theme
    private val languageCode = "your_language_code" // Replace with your actual language code

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Launch ReadyRemitSDK
        ReadyRemit.remitFrom(this, REQUEST_CODE, theme, languageCode)

        // Set inactivity timeout (e.g., 60 seconds)
        ReadyRemit.close(after = 60)
    }
}

(For KYC users only) Implement KYC

If you wish to use the ReadyRemitSDK with the KYC feature, you need to add the camera permission in your AndroidManifest.xml file, since it will require scan the user documents. 

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" 
    package="com.your.package">
    ...
  
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-feature android:name="android.hardware.camera" android:required="false" />
  
</manifest>

Updated 5 months ago