Android Loans SDK Integration

Step 1 - Install and configure

The smallcase Gateway Android Loans SDK is available as a public Maven dependency. No Maven username or password is required to download production releases.

Add the Maven repository

For projects that manage repositories in settings.gradle, add the smallcase production repository inside dependencyResolutionManagement:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()

        maven {
            url = uri("https://artifactory.smallcase.com/artifactory/SCGateway")
        }
    }
}

If your project manages repositories through its project-level build.gradle, add the same Maven repository there instead.

Add the SDK dependency

Add the Loans SDK to your app-level build.gradle:

dependencies {
    // Example version. Check the Android Loans SDK changelog and replace
    // this with the latest recommended production version when necessary.
    implementation "com.smallcase.loans:sdk:5.3.1"
}

Check the Android Loans SDK changelog before integrating or upgrading.

Configure the callback activity

Add the following activity configuration to your app's AndroidManifest.xml:

<activity
    android:name="com.smallcase.loans.features.ScLoanCustomTabActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.BROWSABLE" />
        <category android:name="android.intent.category.DEFAULT" />

        <data
            android:host="<YOUR_GATEWAY_NAME>"
            android:scheme="scgateway-loans" />
    </intent-filter>
</activity>

Replace <YOUR_GATEWAY_NAME> with the unique gateway name provided for your integration.

The value must match the gatewayName passed to ScLoanConfig.

Step 2 - Set up the environment

Before triggering a loan interaction, initialise the SDK by calling setup on the ScLoan object.

All public SDK types are available under com.smallcase.loans.core.external.

Import the types used in this guide:

import com.smallcase.loans.core.external.ScLoan
import com.smallcase.loans.core.external.ScLoanColorScheme
import com.smallcase.loans.core.external.ScLoanConfig
import com.smallcase.loans.core.external.ScLoanEnvironment
import com.smallcase.loans.core.external.ScLoanError
import com.smallcase.loans.core.external.ScLoanInfo
import com.smallcase.loans.core.external.ScLoanResult
import com.smallcase.loans.core.external.ScLoanSuccess

You can alternatively use:

import com.smallcase.loans.core.external.*

Call setup as early as practical in your application lifecycle:

ScLoan.setup(
    config = ScLoanConfig(
        gatewayName = gatewayName
    ),
    listener = object : ScLoanResult {

        override fun onSuccess(response: ScLoanSuccess) {
            // The SDK is ready. Loan interactions can now be triggered.
        }

        override fun onFailure(error: ScLoanError) {
            // SDK setup failed. Handle or retry the setup operation.
        }
    }
)

The public ScLoanConfig model is:

data class ScLoanConfig(
    val gatewayName: String,
    val environment: ScLoanEnvironment = ScLoanEnvironment.PRODUCTION,
)

ScLoanConfig parameters

1. gatewayName - required
   The unique gateway name provided for your integration.

   Example: moneycontrol

2. environment - optional, defaults to PRODUCTION
   Determines which smallcase environment receives SDK API calls.

   When omitted, the selected environment's default URL is used.

Step 3 - Trigger a loan interaction

Use triggerInteraction to start any supported loan interaction.

The SDK determines the appropriate flow - such as loan application, repayment, withdrawal, or servicing - from the interaction token.

Create an interaction token

An interaction token must be created by your backend before calling an SDK interaction method.

The token contains the context for a single user interaction, including the Interaction ID and intended loan action. Treat the token as opaque in the Android application; do not create or modify it on the client.

Learn more in the LAMF glossary and API documentation.

Trigger the interaction

ScLoan.triggerInteraction(
    activity = this,
    config = ScLoanInfo(
        interactionToken = interactionToken
    ),
    listener = object : ScLoanResult {

        override fun onSuccess(response: ScLoanSuccess) {
            // The interaction completed successfully.
        }

        override fun onFailure(error: ScLoanError) {
            // The interaction was cancelled or failed.
        }
    }
)

triggerInteraction parameters

1. activity - required
   The calling Android Activity. The SDK uses it to launch the loan journey.

2. config - required
   An instance of ScLoanInfo containing:

   • interactionToken - required
     The interaction token received from your backend.

   • colorScheme - optional, defaults to unset
     Controls the color scheme used by the native SDK UI and supported loan web pages.

3. listener - required
   A ScLoanResult callback with:

   • onSuccess(response: ScLoanSuccess)
   • onFailure(error: ScLoanError)

Theming (optional)

ScLoanColorScheme is supported in Android Loans SDK 5.2.1 and later.

Pass a color scheme through ScLoanInfo:

ScLoan.triggerInteraction(
    activity = this,
    config = ScLoanInfo(
        interactionToken = interactionToken,
        colorScheme = ScLoanColorScheme.SYSTEM
    ),
    listener = object : ScLoanResult {

        override fun onSuccess(response: ScLoanSuccess) {
            // Handle the successful interaction.
        }

        override fun onFailure(error: ScLoanError) {
            // Handle cancellation or failure.
        }
    }
)

Supported values:

The selected value is applied to:

• Native Loans SDK surfaces
• Chrome Custom Tabs opened by the SDK
• Supported smallcase and creditcase web pages

Third-party pages are not modified by the SDK.

Step 4 - Handle the response

The SDK delivers a result through one of the following callbacks:

• onSuccess with ScLoanSuccess
• onFailure with ScLoanError

Callbacks are delivered on the Android main thread.

Success response

ScLoanSuccess is a public response class with the following fields:

data class ScLoanSuccess(
    val data: String? = null,
    val code: Int = 0,
    val message: String = "success"
) {
    val isSuccess: Boolean
        get() = true
}

response.data is a serialised JSON string. Parse it to access the intent-specific response.

The contents of data depend on the interaction and backend response.

Loan application response

{
  "intent": "LOAN_APPLICATION",
  "userId": "string",
  "loanApplication": {
    "status": "<ApplicationStatus>"
  }
}

Repayment response

{
  "intent": "PAYMENT",
  "userId": "string",
  "payment": {
    "status": "<PaymentStatus>"
  }
}

Withdrawal response

{
  "intent": "WITHDRAW",
  "userId": "string",
  "withdraw": {
    "status": "<WithdrawStatus>"
  }
}

These are representative payloads. Additional fields may be returned depending on the interaction and backend contract.

See Loan application statuses for the supported application statuses and their meanings.

Servicing-dashboard response

The servicing dashboard does not have a single user action that represents successful completion.

When a user closes the servicing dashboard without completing another result-producing action, the SDK calls onFailure with:

• code: 1012
• message: user_cancelled

Handle errors and cancellation

ScLoanError is delivered through onFailure when an interaction fails or is cancelled.

It is a public data class with the following fields:

data class ScLoanError(
    val code: Int,
    val message: String,
    val data: String? = null
) {
    val isSuccess: Boolean
        get() = false
}

error.data, when present, is a serialised JSON string containing additional intent-specific context.

User cancellation

A user closing or backing out of an incomplete interaction can produce:

{
  "isSuccess": false,
  "code": 1012,
  "message": "user_cancelled",
  "data": "{\"intent\":\"LOAN_APPLICATION\",\"loanApplication\":{\"lid\":\"648c66ffc3488a97c9931a2d\",\"status\":\"SIGN_AGREEMENT\"},\"userId\":\"648c6705ee286538f7bebbbb\"}"
}

Existing loan on another platform

An attempt to create a loan when an active loan already exists on another supported platform can produce:

{
  "isSuccess": false,
  "code": 3001,
  "message": "existing_loan_found",
  "data": "{\"intent\":\"LOAN_APPLICATION\",\"userId\":\"64ad01ba0241316d036519c6\"}"
}

These are representative error responses. The contents of data depend on the interaction and backend response.

For the complete list of supported error codes, see Loans SDK error codes.

Deprecated interaction methods

The intent-specific methods below are deprecated. Use triggerInteraction for all new integrations.

// Loan application
ScLoan.apply(
    activity,
    ScLoanInfo(interactionToken),
    listener
)

// Repayment
ScLoan.pay(
    activity,
    ScLoanInfo(interactionToken),
    listener
)

// Withdrawal
ScLoan.withdraw(
    activity,
    ScLoanInfo(interactionToken),
    listener
)

// Servicing dashboard
ScLoan.service(
    activity,
    ScLoanInfo(interactionToken),
    listener
)

Each deprecated method accepts:

activity: Activity
config: ScLoanInfo
listener: ScLoanResult

The interaction token's intent must match the deprecated method being called. A mismatch can return an invalid_intent error.

Use the unified method instead:

ScLoan.triggerInteraction(
    activity = activity,
    config = ScLoanInfo(interactionToken),
    listener = listener
)