LAMF Integration Overview

This document outlines the Loans SDK & API integration to power Loans against Securities.

Product scope

  1. Loan origination (application)
    1. Users could get a loan (LOS) by pledging their securities.
  2. Loan servicing (management)
    1. View loan-related details
    2. Repay principal (partially or fully)
      1. voluntarily repayment
      2. in the event of shortfall (aka margin call) to maintain the required LTV (loan-to-value)
    3. Pay interest overdue, in case the auto-debit fails
    4. Withdraw more principal (upto the sanctioned limit)
    5. View transactions & download loan account statement
    6. View pledged holdings & download statement
    7. Close loan (to release pledged securities)

Learn more about the feature on LAMF: Overview page.

Glossary

KeywordDescription
UnityThis is the name of our API service for partners to integrate.
Unity userLoan applicant user maintained by the Unity service. Each user is a unique combination of PAN and mobile number.
User IDUnique identifier for a Unity user.
Interaction IDA unique identifier for the user's interaction with SDK flow (eg. loan application). The application supports the following interactions - LOAN_APPLICATION, SERVICE, WITHDRAW, PAYMENT
Interaction tokenJWT (JSON Web Token) containing an interaction ID in payload and signed with the shared secret. The token is required for calling SDK methods.

Learn more about Interaction token (JWT)

Server-side APIs

API name

Description

Create unity user

Creates a Unity user by calling this API with the user's PAN, DOB, along with other optional fields. A user can be created once for a PAN. Ensure to link the user ID with the user's account.

Alternatively, if you do not have access to the user's PAN and/or DOB, you may skip this API and create an interaction id for the guest user. Whenever the user submits PAN & DOB in the gateway flow, we will hit your registered webhook with the user ID.

Get unity user details

Fetch the existing unity user against the Unity User ID - this is useful for fetching loans against a user

Create interaction ID

Creates an interaction ID for a given interaction intent & config. Intent can be LOAN_APPLICATION, PAYMENT, WITHDRAW

Get loan application status

Returns current stage of loan application, and disbursement status (if application is submitted).
Possible application stages: REGISTER_LEAD, IMPORT_HOLDINGS, FETCH_CKYC, CONFIRM_OFFER, LINK_BANK_ACCOUNT, PLEDGE_FUNDS, SIGN_AGREEMENT, DISBURSE_LOAN.

Get loan details (for active loan)

Returns all the loan-related data points that will help the partner build the servicing dashboard. This includes the sanctioned amount, cash withdrawn, interest rate, available disbursement amount, recent & upcoming transactions, boolean flags to determine UI states (eg. interest bounce), and more.

Get pledged holdings (JSON data)

Returns list of pledged holdings - in raw data as well as PDF format (for user download)

Get transactions history (JSON data)

Returns list of transactions - in raw data as well as SOA PDF format (for user download)

Addon APIs

API nameDescription
Credit limit simulationReturns loan amount that can be availed against a list of mutual fund holdings. This API can be integrated for nudging users to apply for a loan, if the partner has access to the user's MF holdings.

Loan closure APIs

API nameDescription
Get total pending amount (for loan closure)Retrieve the pending amount user has to pay to close their existing loan
Request loan closureThe API will initiate the request to close an existing user loan. It will return appropriate errors if, for some reason, loan closure request cannot be initiated

Client-side SDK

  • Client-side SDK is required for certain user flows like loan applications, all kinds of payments by the user, and loan closure.
  • Gateway provides Web SDK (Javascript), native SDKs (Android, iOS), and wrapper SDKs (React Native, Flutter, Cordova).

SDK Interface

class ScLoan {
  constructor({ gatewayName }) {};

  // LOS (Loan origination)
  apply({ interactionToken }) {};


  // LMS (Loan servicing)
  pay({ interactionToken }) {};
  withdraw({ interactionToken }) {};
}
class ScLoan {
    /**
     * @typedef {Object} ScLoanConfig
     * @property {String} gatewayName
     * @property {'production'}  environment - environment
     */

    /**
     * Setup ScLoans
     *
     * @param {ScLoanConfig} config
     * @returns {Promise<String>}
     */
    const setup = async (config) => {};

    /**
     * LoanInfo object required for every SDK interaction
     * @typedef {Object} LoanInfo
     * @property {String} interactionToken
     */

    /**
     * Triggers the user journey for loan application.
     *
     * @param {LoanInfo} loanInfo
     * @returns {Promise<String>}
     */
    const apply = async (loanInfo) => {};

    /**
     * Triggers the user journey for loan repayment.
     *
     * @param {LoanInfo} loanInfo
     * @returns {Promise<String>}
     */
    const pay = async (loanInfo) => {};

    /**
     * Triggers the user journey for withdrawing the loan amount.
     *
     * @param {LoanInfo} loanInfo
     * @returns {Promise<String>}
     */
    const withdraw = async (loanInfo) => {};
}
object SCLoan {
    // Setup the SCLoan SDK
    fun setup(config: SCLoanConfig, listener: SCLoanResult)

    // Triggers the user journey for loan application
    fun apply(activity: AppCompatActivity, config: ScLoanInfo, listener: SCLoanResult)

    // Triggers the user journey for loan repayment
    fun pay(activity: AppCompatActivity, config: ScLoanInfo, listener: SCLoanResult)

    // Triggers the user journey for withdrawing the loan amount
    fun withdraw(activity: AppCompatActivity, config: ScLoanInfo, listener: SCLoanResult)
}

// Callback interface for every SDK method:
interface SCLoanResult {
    fun onSuccess(response: SCLoanSuccess)

    fun onFailure(error: SCLoanError)
}

// Success callback returns
data class SCLoanSuccess(val isSuccess: Boolean, val data: String?)

// Failure callback returns
data class SCLoanError(val code: Int, val message: String, val data: String?)

// LoanInfo object required for every SDK interaction
class ScLoanInfo(val interactionToken: String)
public class SCLoan {
  // Setup the SCLoan SDK
  @objc public func setup(
    config: SCLoanConfig,
    completion: @escaping (SCLoanSuccess?, SCLoanError?) -> Void
  )

  // where SCLoanConfig is:
  class SCLoanConfig: NSObject {
    let gatewayName: String?
    let environment: SCLoanEnvironment?
  }

  // Triggers the user journey for loan application
  @objc public func apply(
    presentingController: UIViewController,
    loanInfo: LoanInfo,
    completion: @escaping (SCLoanSuccess?, SCLoanError?) -> Void
  )

  // Triggers the user journey for loan repayment
  @objc public func pay(
    presentingController: UIViewController,
    loanInfo: LoanInfo,
    completion: @escaping (SCLoanSuccess?, SCLoanError?) -> Void
  )

  // Triggers the user journey for withdrawing the loan amount
  @objc public func withdraw(
    presentingController: UIViewController,
    loanInfo: LoanInfo,
    completion: @escaping (SCLoanSuccess?, SCLoanError?) -> Void
  )

}

// Where the success object is
public class SCLoanSuccess: NSObject {
  let isSuccess: Bool
  let data: String?
}

// And the error object is
public class SCLoanError: NSError {
  let isSuccess: Bool
  let errorCode: Int
  let errorMessage: String
  let data: String?
}

// LoanInfo object required for every SDK interaction
class LoanInfo: NSObject {
  let interactionToken: String
}