Android Loans SDK Integration

Step 1 - Install and Configure

smallcase Gateway Android Loans SDK is available as a public gradle dependency. To install the Android SDK, add it to your app level build.gradle file.

// Include maven repository url and authentication details
repositories {
    maven {
        url "https://artifactory.smallcase.com/artifactory/SCGateway"
        credentials {
            username "${artifactory_user}"
            password "${artifactory_password}"
        }
    }
}

// Add smallcase Gateway SDK as a dependency
dependencies {
  implementation 'com.smallcase.gateway:sdk:${version}'
}

• Replace ${version} with the latest version available.
  Eg - Current version is 3.12.1
• Replace "${artifactory_user}" and "${artifactory_password}" with user name and password which is given to all integration partners.

Configuration should happen as early as possible in your application's lifecycle. Configure smallcase Gateway Android SDK via 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 unique host name which is given to every integration partners.

🚧

Note

If your app targets Android 12 or higher you must explicitly declare the android:exported attribute for these activities. If an activity doesn't have an explicitly-declared value for android:exported, your app can't be installed on a device that runs Android 12 or higher.

Step 2- Environment Setup

To start using the loans SDK, set up the loans SDK with the desired configuration by calling the setup method which is available as a method of ScLoan class.

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

    override fun onSuccess(response: ScLoanSuccess) {
        //Handle response
    }
    
    override fun onFailure(error: ScLoanError) {
        //Handle the error 
    }

})

Here's a look into ScLoanConfig class.

class ScLoanConfig(
    val gatewayName: String,
    val environment: ScLoanEnvironment
) 

Params :

1. environment (required): This defines the Url environment to which all the gateway apis would point to
   Possible values - ScLoanEnvironment.PRODUCTION
2. gatewayName (required): This is a unique name given to every gateway consumer
   Eg : moneycontrol

📘

Note

Call setup every time there is any change in the setup.
setup must be the first method to be fired. If setup is not called all other methods will not work.

Step 3 - Call the relevant method for each functionality

Based on the action to be performed, trigger the relevant method of ScLoan class.

Interaction Token should be created before calling any Loans related method

All the Loans methods on the SDK instance require an interaction token to be passed as an argument. The JWT token holds the context of user action in the form of Interaction ID. It is a unique, one-time-use ID created each time a borrower wants to interact with their loan via SDK. Learn what & how of interaction ID & token in Glossary & API documentation.

1. apply: start or resume loan application

You can start or resume a loan application by calling the apply method on the SDK.

ScLoan.apply(ScLoanInfo(interactionToken), listener = object : ScLoanResult {

    override fun onSuccess(response: ScLoanSuccess) {
        //Handle response
    }
    
    override fun onFailure(error: ScLoanError) {
        //Handle the error 
    }

})

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

2. pay: repayments (principal, bounced interest, charges due)

For repayment, the gateway flow can be triggered opened by calling the pay method on the SDK -

ScLoan.pay(ScLoanInfo(interactionToken), listener = object : ScLoanResult {

    override fun onSuccess(response: ScLoanSuccess) {
        //Handle response
    }
    
    override fun onFailure(error: ScLoanError) {
        //Handle the error 
    }

})

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

3. withdraw: withdraw un-utilised credit limit

You can withdraw from your approved credit by calling the withdraw method on the SDK.

ScLoan.withdraw(ScLoanInfo(interactionToken), listener = object : ScLoanResult {

    override fun onSuccess(response: ScLoanSuccess) {
        //Handle response
    }
    
    override fun onFailure(error: ScLoanError) {
        //Handle the error 
    }

})

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

4. service: view loan dashboard (aka servicing dashboard)

This will open up Gateway's UI for servicing dashboard where user can view all of their loan details and take any further action (eg. repayment, withdrawal, closure).

ScLoan.service(ScLoanInfo(interactionToken), listener = object : ScLoanResult {

    override fun onSuccess(response: ScLoanSuccess) {
        //Handle response
    }
    
    override fun onFailure(error: ScLoanError) {
        //Handle the error 
    }

})

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

Step 4 - Handle response or error

If the user's intended action is completed, the Future returned by the method will resolve with a success response. Else, if flow ends without action completion, an exception is thrown.

Success responses

ScLoanSuccess is an internal class that denotes a success response on the SDK.
The SDK returns a serialised version of this object whose signature is defined below.

{
  "isSuccess": true,
  "data": {
    "intent": "LOAN_APPLICATION",
    "userId": "string",
    "loanApplication": {
      "status": "<ApplicationStatus>" // possible enum values below
    }
  }
}

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

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

// .service() promise will always be rejected with an error.
// This is because there's no specific user intent that should cause a success.

Error response

ScLoanError is an internal class that denotes an error response on the SDK.
The SDK throws a serialised version of this object whose signature is defined below.

{
  "isSuccess": false,
  "code": "number", // enums below
  "message": "string", // enums below
  "data"?: {} // intent specific data point
}

// case where user drops off before applying
{
  "isSuccess": false,
  "code": 1012,
  "message": "user_cancelled",
  "data": {
    "intent": "LOAN_APPLICATION",
    "loanApplication": {
      "lid": "648c66ffc3488a97c9931a2d",
      "status": "SIGN_AGREEMENT"
    },
    "userId": "648c6705ee286538f7bebbbb"
  }
}

// case where loan is active with another platform
{
  "isSuccess": false,
  "code": 3001,
  "message": "existing_loan_found",
  "data": {
    "intent": "LOAN_APPLICATION",
    "userId": "64ad01ba0241316d036519c6"
  }
}

// other error codes bellow

The error code <> message mapping -

👋

Got queries? Ask our AM for an integrations support email. If an email thread exists, post queries as a reply to that.