Javascript Loans SDK Integration

🙌

Hey, before you read further

Must read: LAMF: Integration overview

Good to read: LAMF: Product Overview

Get started with how to integrate our JS SDK has on your client-side website.

Step 1 - Load the SDK from URL

On the relevant pages of your website, include our Javascript SDK using the URL -

<script src="https://gateway.smallcase.com/scdk/2.0.0/scdk.js" type="text/javascript" />

<script src="https://gateway.smallcase.com/scdk/2.0.0/lasSdk.js" type="text/javascript" />

Since the SDK is not versioned, all future updates will be applied on the fly. It will be ensured that the changes are non-breaking.

Step 2 - Create an Object Instance of ScLoan class

Once the script executes after loading, ScLoan class is available in JavaScript's global scope. All LAMF methods are to be called on the instance of this class.

const lasSdkInstance = new window.ScLoan({
  // ! gateway name integration key is shared by business team
  gatewayName: "<gateway_name>"
});

Step 3 - Call the relevant method for each functionality

Based on the action to be performed, trigger the relevant method of lasSdkInstance object.

Interaction Token should be created before calling any LAMF related method

All the LAMF 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.

SDK Response (Success or Error)

SDK methods immediately return a JS promise and are asynchronously resolved or rejected whenever the flow ends. If the user completes the intended action, the promise gets resolved with a successful response. Else, it gets rejected with an error.

1. apply: start or resume loan application

You can start open the loan application UI by calling the apply method on the SDK.

try {
  const response = await lasSdkInstance.apply({
    interactionToken: "<interaction_token>",
  });
  // handle success response
} catch (e) {
  // handle error
}

The method returns a Promise. At the close of the flow, the same promise is either resolved or rejected based on whether the user successfully applied for the loan. More details in the next step.

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

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

try {
  const response = await lasSdkInstance.pay({
    interactionToken: "<interaction_token>",
  });
  // handle success response
} catch (e) {
  // handle error
}

Go to the next step for response handling.

3. withdraw: withdraw unutilized credit limit

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

try {
  const response = await lasSdkInstance.withdraw({
    interactionToken: "<interaction_token>",
  });
  // handle success response
} catch (e) {
  // handle error
}

The method returns a Promise. Go to the next step for success and error 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 {
  const dashboard = lasSdkInstance.service({
    interactionToken: "<interaction_token>",
    target: "<element id>"
  });
  const response = await dashboard.task;
  // handle success response
} catch (e) {
  // handle error
}

Notice an additional parameter target is required. The sdk will find an element using getElementById(target) and open the servicing dashboard inside the element. Its left up to the host application to style the target element as preferred. Additionally, .service() method returns an object instead of a promise. The object contains

1. close(), a method that can be used to close the dashboard
2. task, a promise that is resolved when user intends to close/go-back from servicing dashboard. You may await on this promise to get SDK response

Step 4 - Handle response or error

If the user's intended action is completed, the Promise returned by the method will resolve with a success response. Else, if flow ends without action completion, it's resolved with an error.

Success responses

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

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

{
 "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

When the Gateway UI gets closed without the user completing their intent, an instance of ScLoanError class is returned. ScLoanError is a sub-class of the Javascript Error. It also provides some information related to the interaction.

type ScLoanError = {
  name: "ScLoanError",
  code: "number", // enums below
  message: "string", // enums below
  data?: Object // intent specific data point
}

// case where user drops off before applying
{
  "errorName": "ScLoanError",
  "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
{
  "errorName": "ScLoanError",
  "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.