Flutter Loans SDK Integration

Integrate smallcase loans Flutter SDK to allow your users to apply for loans, pay, withdraw, and much more

Step 1 - Install and Configure

The loans Flutter SDK by smallcase Gateway named scloanscan be installed by the below guide.
Follow the installation guide here.

A. Android

  1. 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.

  1. Add the below configurations to your proguard-rules.pro file at android/app/proguard-rules.pro in order to use flutter plugins without any hiccups in release mode:
#Flutter Wrapper
-keep class io.flutter.app.** { *; }
-keep class io.flutter.plugin.**  { *; }
-keep class io.flutter.util.**  { *; }
-keep class io.flutter.view.**  { *; }
-keep class io.flutter.**  { *; }
-keep class io.flutter.plugins.**  { *; }

# Add project specific ProGuard rules here.
# By default, the flags in this file are appended to flags specified
# in /usr/local/google/home/samstern/android-sdk-linux/tools/proguard/proguard-android.txt
# You can edit the include path and order by changing the proguardFiles
# directive in build.gradle.
#
# For more details, see
#   http://developer.android.com/guide/developing/tools/proguard.html

# Add any project specific keep options here:

# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
#   public *;
#}

# Uncomment this to preserve the line number information for
# debugging stack traces.
-keepattributes SourceFile,LineNumberTable

# If you keep the line number information, uncomment this to
# hide the original source file name.
#-renamesourcefileattribute SourceFile

# Keep custom model classes
-keep class com.google.firebase.** { *; }


# To ignore minifyEnabled: true error
# https://github.com/flutter/flutter/issues/19250
#https://github.com/flutter/flutter/issues/37441
-ignorewarnings
-keep class * {
    public private *;
}

B. iOS

Go to your project's ios folder run pod install within the directory

📘

Note

Running pod update after adding a source will trigger a clone of the the source repo. This operation might take time when pod update is run for the first time. Subsequent updates will be faster.

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 static method of ScLoan class.

try {
    final config = ScLoanConfig(environment, gateway)
    final ScLoanSuccess response = await ScLoan.setup(config);
    
    // Handle the response
    
} on ScLoanError catch (e) {
    
    // Handle exception
    
}

Params :

  1. ScLoanConfig :
    1. environment (required): This defines the Url environment to which all the gateway apis would point to
      Possible values - ScLoanEnvironment.PRODUCTION
    2. gateway (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.

try {
    final loanInfo = ScLoanInfo(interactionToken)
    final ScLoanSuccess response = await ScLoan.apply(loanInfo);
    
    // Handle the response
    
} on ScLoanError catch (e) {
    
    // Handle exception
    
}

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 -


try {
    final loanInfo = ScLoanInfo(interactionToken)
    final ScLoanSuccess response = await ScLoan.pay(loanInfo);
    
    // Handle the response
    
} on ScLoanError catch (e) {
    
    // Handle exception
    
}

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.

try {
    final loanInfo = ScLoanInfo(interactionToken)
    final ScLoanSuccess response = await ScLoan.withdraw(loanInfo);
    
    // Handle the response
    
} on ScLoanError catch (e) {
    
    // Handle exception
    
}

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

try {
    final loanInfo = ScLoanInfo(interactionToken)
    final ScLoanSuccess response = await ScLoan.service(loanInfo);
    
    // Handle the response
    
} on ScLoanError catch (e) {
    
    // Handle exception
    
}

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 Flutter 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.
What are possible values of Application Status?
Application statusDescription
REGISTER_LEADInitial status of the application
IMPORT_HOLDINGSUser dropped off without completing the holdings import step
CONFIRM_OFFERUser completed holdings import but didn't continue with the credit limit available
FETCH_CKYCUser continued with credit limit available but dropped off before completing KYC
LINK_BANK_ACCOUNTUser completed KYC but dropped off before entering bank details & setting up e-mandate
PLEDGE_FUNDSUser created e-mandate but didn't complete the pledging of mutual funds
SUBMISSION_FAILEDUser pledged the mutual funds but due to some issues, the application submission to lender failed & the agreement was not generated
SIGN_AGREEMENTUser pledged the mutual funds & agreement was generated but user dropped off before signing the agreement
SUBMITTEDUser signed the agreement and the loan application is available to the lender for approval
APPROVEDLoan application was approved by the lender
DISBURSEMENT_REQUESTEDDisbursement for the loan amount has been requested
DISBURSEDLoan amount has been disbursed by the lender to user's bank account

Error response

ScLoanError is an internal class that denotes an error response on the SDK.
The Flutter 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 -

Error codeCorresponding Error messagereason
1012user_cancelledThe user aborted the flow by closing/abandoning the UI
1031contact_supportThe user wants to customer support and has tapped the contact icon. Redirect them to the support page or trigger chat page.
2000internal_error
2001missing_url_params
3001existing_loan_found
4000invalid_request
4001partner_inactive
4002guest_not_allowed
4003interaction_expired
4004invalid_intent
4005invalid_interaction
4006invalid_intent_config
4007api_secret_mismatch
4008invalid_auth_token

👋

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