An Interaction ID is a one-time identifier used to initialise the Gateway SDK and launch a journey for a user. Every interaction is created with an intent that determines what the SDK does.

Supported intents

• LOAN_APPLICATION — Start or resume a new loan application. Can also be used to pass offers/discounts to the user on the loan journey, or to change the processing fee / rate of interest for a loan application via a new referrerCode.

• SERVICE — Display the servicing dashboard for a loan in submitted / post-submission state.

• LAUNCH (New) — Provides an easy way to integrate the SDK if you don't wish to manage user and loan application states on your backend. Internally, the intent resolves to either LOAN_APPLICATION or SERVICE, based on the user's current state.

  Resolves to LOAN_APPLICATION when:

  1. It's a new user — starts a new loan application.
  2. The user has an active loan application — resumes the loan application.

  Resolves to SERVICE when the user has an active loan (post application submission).

  Note: This intent never resumes a top-up loan application. The SDK launches the servicing dashboard, which has an entry point for the user to resume the top-up journey.

  Use cases where LAUNCH can be considered:

  1. You have a single/common entry point for the Loans SDK in your app, irrespective of the user's loan application state.
  2. You want to expose a generic URL to acquire users for credit (e.g. https://partner.smallcase.com/launch/loan-distribution-partners).

• LOAN_APPLICATION:TOP_UP — Start or resume a top-up loan application from your landing page when the user has an active, disbursed loan.
• LOAN_APPLICATION:RENEWAL — Start or resume a loan application renewal journey from your landing page when the user has an active, disbursed loan.
• WITHDRAW — Launch a withdrawal flow for an existing, disbursed loan from your landing page. Behaviour varies per lender: for Bajaj Finserv and DSP Finance, the SDK triggers a backend-based withdrawal flow and no user journey is launched; for South Indian Bank, a user journey is launched where the user authenticates the request via an email OTP flow.
• PAYMENT — Launch a payment flow (principal, interest, other charges) for an active, disbursed loan. The flow varies per lender, and a payment-gateway flow is launched wherever supported.

Connected vs guest mode

Every intent can be created in one of two modes:

• Connected user — pass a userId in the request. The user starts the journey by authenticating directly with a mobile OTP; they don't have to input their mobile number on the journey.
• Guest — no userId is passed. The SDK first has to identify the user, so the journey starts with the user entering their phone number (the same as the authContact in Create unity user), followed by the OTP.

Request payloads by intent

LOAN_APPLICATION / LAUNCH for connected user

{
    "intent": "LOAN_APPLICATION",
    "config": {
        "assetType": "MUTUALFUND", // OR "STOCKS"
        "userId": "646f5a65a4ae4db366623638",
        "opaqueId": "123",
        "referrer": "gatewaydemo" // optional - can be passed if you want to change the referrerCode for this loan application - only respected before loan agreement generation. Defaults to your partner key, which is also your default referrerCode
    },
    "offers": [ // optional
        {
            "offerCode": "LAMF1", // shown to the user on the journey
            "offerId": "1233234jd", // unique identifier for an offer
            "expiryDate": "2025-10-09T14:30:00Z",
            "listed": true,
            "description": "",
            "autoApply": false, // if true, the offer is applied automatically
            "applicableAmountRangeMin": 1000,
            "discount": {
                "type": "ABSOLUTE",
                "value": 10, //the discount amount
                "maxValue": 10 // keep same as the value
            },
            "applicableOn": "PROCESSING_FEE" // only PF discounts are supported as of now
        }
    ]
}

The offers array is optional — include it to pass an offer/discount to the user on the loan journey.

Note for reapplication (after closing loan)

For a user, who has closed an existing loan, and wants to apply for a loan, an interactionId can be created again as mentioned in the above payload.

A new loan journey will be created for the user, and the new loan application (LID) will be shared in the response.

Response

{
    "code": 0,
    "data": {
        "createdAt": 1686253244,
        "expireAt": 1686253544,
        "guest": false,
        "intent": "LOAN_APPLICATION",
        "interactionId": "INT64822ebcb406ec46428efac0",
        "lid": "646f5a65a4ae4db366623639",
        "lender": "bajaj_finserv",
        "partner": "gatewaydemo-dev",
        "status": "CREATED",
        "userId": "646f5a65a4ae4db366623638"
    },
    "message": "SUCCESS"
}

LOAN_APPLICATION / LAUNCH for guest user

Since no userId is passed, this is a guest journey — the SDK first identifies the user via phone number + OTP, then starts the application.

{
    "intent": "LOAN_APPLICATION",
    "config": {
        "assetType": "MUTUALFUND" // OR "STOCKS"
    }
}

All optional fields listed in the connected-user example above are also supported in the guest payload.

SERVICE with connected user

{
    "intent": "SERVICE",
    "config": {
        "assetType": "MUTUALFUND", // OR "STOCKS"
        "userId": "66c5902eb1a7a3d946bf99c8",
        "opaqueId": ""
    }
}

Servicing also functions in guest mode — if userId is not passed in the payload, the SDK identifies the user via phone number + OTP before showing the dashboard.

LOAN_APPLICATION:TOP_UP for connected user

For a user with an active loan application, user might want to -

1. Avail a higher loan amount by additionally pledging more funds, OR
2. Enhance the sanction amount due to NAV appreciation on the already pledged funds.

For such user, a top-up journey can be initiated by creating an interactionId with LOAN_APPLICATION:TOP_UP intent

On initiating a top-up journey, user can perform -

1. Fetch additional holdings and confirm their top-up amount.
2. Perform KYC (conditionally skipped)
3. Setup mandate for the revised loan amount, followed by pledging of the additional funds
4. Sign the agreement with the revised loan amount
5. Trigger disbursement disbursement post lodgement of additional funds is done

{
    "intent": "LOAN_APPLICATION:TOP_UP",
    "config": {
        "assetType": "MUTUALFUND", // OR "STOCKS"
        "userId": "646f5a65a4ae4db366623638",
        "opaqueId": "123" 
    }
}

LOAN_APPLICATION:RENEWAL for connected user

For renewing an existing loan which is about to expire, a renewal journey can be initiated for the user by launching the journey with an interactionId of LOAN_APPLICATION:RENEWAL intent

{
    "intent": "LOAN_APPLICATION:RENEWAL",
    "config": {
      "assetType": "MUTUALFUND", // OR "STOCKS"
      "userId": "646f5a65a4ae4db366623638",
      "opaqueId": "123" ,      
      "isAutoDisbursal": false 
    }
}

On initiating a renewal journey,

1. User would land on the loan card screen, where user can confirm the loan amount and setup new mandate
2. Next, user can proceed to sign the agreement
3. Once tenure is extended, the servicing dashboard would now refer to the new application (i.e the loan application ID aka. LID for the renewal loan). Previous LID would be marked as CLOSED

WITHDRAW with connected user

{
    "intent": "WITHDRAW",
    "config": {
        "amount": "8901.01",
        "assetType": "MUTUALFUND", // OR "STOCKS"
        "opaqueId": "Sdfjhksljhf53798234",
        "userId": "6481d77b1bd11a820a13e0cf",
        "lid": "16481d77b1bd11a820a13e0c"
    }
}

PAYMENT with connected user

Additionally, this intent mandates config.type. Following values are accepted in the field:

1. "bounced_interest"
2. "principal"
3. "shortfall"
4. "loan_closure"

{
    "intent": "PAYMENT",
    "config": {
        "type": "principal",
        "lid": "648acdf8da1ae7fbbfaa713f",
        "assetType": "MUTUALFUND", // OR "STOCKS"
        "opaqueId": "Sdfjhksljhf53798234",
        "userId": "648ace0076fd318b1bfdeb40"
    }
}