Handling New Users (Deep Linking & Seamless Redirect)

One of Localcredit’s most powerful integration features is the seamless onboarding flow for new users. When a user in your app has no Localcredit score yet, you can redirect them directly to the official Localcredit Telegram Mini App.

They complete onboarding there and return automatically to your app with their fresh score ready to query.This flow eliminates friction, increases conversion rates, and lets you leverage Localcredit’s optimized onboarding experience without building it yourself.

How It Works

1. Your app queries the user’s proof → API returns “no score” or invalid proof.

2. You prompt the user: “Create your Localcredit score in 2 minutes to unlock better terms?”

3. Deep-link to@LocalcreditBot/app with return parameters.

4. User onboards in the official Mini App (wallet connect + optional boosters).

5. After completion, Localcredit closes the WebApp and returns control with the new proof.

6. Your app detects the return, fetches the new score, and continues the flow (e.g., loan approval).

Deep Link Format

https://t.me/LocalcreditBot/app?startapp=return_{returnUrl}_app_{yourAppId}

Parameters:

• return_{returnUrl}: URL-encoded callback URL where the user should land after onboarding.

  • For another Telegram Mini App: yourminiapp://localcredit-return

  • For web apps: your full HTTPS callback page (e.g., https://yourapp.com/localcredit-return)

• app_{yourAppId}: Optional identifier for analytics (e.g., “lending_pro_123”). Helps track conversions.

JavaScript/TypeScript Example (using the SDK)typescript

import { Localcredit } from '@localcredit/sdk-js';

const lc = new Localcredit({ apiKey: 'your_key' });

async function checkScoreOrOnboard() {
  try {
    const userProof = await lc.requestProof();
    const result = await lc.getScore(userProof);
    // User has score → proceed with your app logic
    showApprovedLoan(result);
  } catch (error) {
    if (error.code === 'PROOF_NOT_FOUND' || error.code === 'NO_SCORE') {
      // Redirect to Localcredit for onboarding
      await lc.redirectToOnboarding({
        returnUrl: window.location.href,     // return to current page
        // or for Mini App: 'yourminiapp://return',
        appId: 'my_lending_app_v1'           // optional tracking
      });
    } else {
      // Handle other errors
      showError(error.message);
    }
  }
}

The SDK automatically constructs the correct deep link and opens it in Telegram (or browser fallback).Handling the Return in Your AppAfter onboarding, Localcredit will:

• Close the Mini App (Telegram.WebApp.close())

• Redirect to your provided returnUrl with query params:

  ?lc_proof=0xnewproof...&lc_status=success

Web App Return Handler Exampletypescript

// On page load or route change
const urlParams = new URLSearchParams(window.location.search);
const newProof = urlParams.get('lc_proof');

if (newProof) {
  // Fresh proof from Localcredit onboarding
  const result = await lc.getScore(newProof);
  showApprovedLoan(result); // continue user journey
  // Clean URL optionally
  window.history.replaceState({}, '', window.location.pathname);
}

Telegram Mini App Return Use Telegram’s WebApp API to detect return:typescript

Telegram.WebApp.ready();
if (Telegram.WebApp.initDataUnsafe.start_param?.includes('return_')) {
  // User returned from Localcredit
  const freshProof = await lc.extractProofFromReturn();
  const result = await lc.getScore(freshProof);
  // Proceed
}

Best Practices

• Show a clear prompt before redirect: explain the 2-minute benefit.

• Pre-fill context if possible (e.g., “Signing up via MyLendingApp” message in Localcredit).

• Track conversion with your appId in analytics.

• Fallback gracefully if redirect is interrupted (e.g., “Finish in Localcredit and return here”).

This flow has proven to dramatically increase user completion rates while keeping your app lean. Users love the smooth handoff, and you get higher-quality borrowers faster.Full examples and troubleshooting at docs.localcredit.org/deep-linking.