Hosted Handoff

Hosted handoff is the ownership boundary in Hybrid Experience. Your product owns the borrower journey until the borrower selects an offer. After that, Aarthik Labs takes over the selected-offer execution inside Hosted Experience.

Use Hosted handoff after the borrower has chosen a specific offerID in your UI.

Handoff Endpoint

GET /api/v1/hybrid/personal-loan/borrowers/{borrowerProviderID}/journey/offers/{offerID}/hosted
GET /api/v1/hybrid/gold-loan/borrowers/{borrowerProviderID}/journey/offers/{offerID}/branches/{branchID}/hosted
GET /api/v1/hybrid/loan-against-mutual-funds/borrowers/{borrowerProviderID}/journey/offers/{offerID}/hosted
GET /api/v1/hybrid/business-loan/borrowers/{borrowerProviderID}/journey/offers/{offerID}/hosted

This endpoint returns a short-lived hosted_url for the selected offer. For non-Gold products, Aarthik Labs configuration scoped to the tenant, application, and lender controls API acceptance. The configured value wins and defaults to enabled when no policy exists.

isOfferAccepted remains accepted for backward compatibility, but every supplied value is ignored. offer_acceptance.requested reports the effective server-controlled decision; check offer_acceptance.applied to see whether this call applied acceptance.

The third API returns a Hosted URL immediately for supported states:

| State | hosted_url behavior | | --- | --- | --- | | External lender URL ready | Opens a minimal loader and automatically redirects to the lender. | | External lender URL pending | Opens the same minimal unbranded loader, which waits internally and redirects when ready. The integrator does not poll this API. | | Stage complete or journey terminal | Opens the Hosted offer and journey tracker for status, offer details, servicing, payments, and IGM actions when available. |

Single-redirection journeys resolve LENDER_REDIRECTION. Multiple-redirection journeys resolve the first incomplete borrower action in one shared order: KYC, bank mandate when applicable, e-mandate, then loan agreement. A ready response never exposes the raw lender destination.

For Personal Loan responses where acceptance was applied, opening the URL automatically forwards the borrower to the lender’s current step when one exists. A single-redirection journey goes to the lender destination. A multiple-redirection journey goes to the current external stage, such as KYC, e-mandate, or loan agreement/e-sign. The borrower does not need to click Verify or interact with an Aarthik Labs screen while waiting.

Bank mandate remains Hosted when the borrower action belongs to Aarthik Labs or must be completed locally. A server policy that disables API acceptance preserves the standard Hosted review. If a direct handoff expires or cannot be completed, request a fresh hosted_url; do not ask the borrower to share the complete Hosted URL or its fragment.

Supported LAMF API acceptance is limited to online single-redirection journeys. Unsupported LAMF modes return the non-retryable HYBRID_HOSTED_STAGE_UNSUPPORTED error. Gold Loan behavior is unchanged and continues to use its existing branch-confirmation contract.

For Business Loans, the selected offer can have productType: BUSINESS_LOAN or productType: PERSONAL_LOAN. Send its offerID and the same journeyID used for offer polling. The response includes the selected product in data.journey.type and data.journey.offer.productType.

Your back-end should call this endpoint. Your front-end should receive only the URL it needs to open.

Handoff Flow

What Hosted Experience Handles After Handoff

After your app opens the Hosted URL, Aarthik Labs handles the downstream borrower journey. Depending on the lender and product path, this can include:

• offer detail confirmation
• KFS review
• KYC
• bank mandate or e-mandate
• loan agreement and e-sign
• lender redirects
• lender re-entry after external steps
• disbursal progression
• post-disbursal servicing

This is the same hosted execution layer used by Hosted Experience. Hybrid Experience simply enters it later, after the borrower has selected an offer inside your own product.

Loan Against Mutual Funds Handoff Detail

For Loan Against Mutual Funds, the selected offer returned with the Hosted handoff follows the LAMF facility selected by the borrower.

LAMF hosted handoff responses do not expose minimumLoanAmount, maximumLoanAmount, or ltvRatio. The API Reference includes separate Credit Line and Term Loan examples for the same handoff endpoint.

Gold Loan Handoff Detail

For Gold Loans, pass the selected branch ID from the Gold Loan offers polling response in the handoff path. The Hosted handoff response returns the selected lender, selected offer, relationship manager details from the lender’s fulfillment-agent data, and the fresh hosted_url.

{
  "data": {
    "hosted_url": "https://credit.aarthiklabs.com/lab/handoff?handoff=...",
    "expires_at": "2026-05-14T09:16:30.000Z",
    "target_offer_id": "offer_gl_001",
    "target_branch_id": "branch_001",
    "target_journey_id": "journey_gl_001",
    "journey": {
      "type": "GOLD_LOAN",
      "status": "OFFERED",
      "lender": {
        "id": "lender_001",
        "lender_name": "Gold Lender",
        "lender_gro_name": "Support Lead",
        "lender_gro_email": "gro@example.com",
        "lender_customer_support_contact_number": "1800123456"
      },
      "offer": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "accepted": false,
        "expired": false,
        "amountPrincipal": "400000",
        "amountTotalInterestPayable": "42300",
        "amountNetDisbursedAmount": "392000",
        "offerTerm": "5 months",
        "interestRate": "12.00",
        "interestType": "FIXED",
        "annualPercentageRate": "5.00",
        "numberOfInstallments": 5,
        "coolOffPeriod": "3 days",
        "termsAndConditionsLink": "https://example.com/tnc.pdf",
        "keyFactsStatementLink": "https://example.com/kfs.pdf",
        "applicationFees": "0",
        "foreclosureFees": "0",
        "interestRateConversionCharges": "0",
        "delayPenaltyFees": "0",
        "otherPenaltyFees": "0",
        "processingFees": "8000",
        "otherUpfrontCharges": "0",
        "insuranceCharges": "0",
        "otherCharges": "0",
        "installments": [
          {
            "serialNumber": 1,
            "type": "INSTALLMENT",
            "amount": "12000.00",
            "status": "PAID | OVERDUE | NOT-DUE",
            "dueDate": "2024-08-01"
          }
        ],
        "relationshipManager": {
          "name": "Rajesh Sharma",
          "phone": "+91-9876543210"
        }
      }
    }
  }
}

Opening The URL

Open the returned URL immediately in the borrower browser, webview, or app shell.

Do not:

• store the URL as a long-term resume link
• expose your API key to the front-end
• attempt to reconstruct the Hosted URL client-side
• reuse old Hosted URLs after expiry

If the borrower returns later, call the Hosted handoff endpoint again for the selected offer and open the fresh URL.

Mobile Applications

If your Hybrid journey runs inside a mobile app, the hosted handoff should use the mobile handling documented under the Hybrid Integrations Guide:

• register the mobile bridge before loading hosted screens
• support external lender pages and return behavior
• allow camera, file, and related permissions when required by the journey
• handle exit events cleanly

Mobile app requirement: Opening hosted_url is not the end of the Hybrid journey. It starts the Hosted selected-offer journey. If the borrower is inside your mobile app, register and handle the Mobile App Bridge before loading the URL so lender verification steps can open, resume, and exit correctly.

Read the mobile application docs for the detailed bridge and permission requirements:

• Bridge
• Permissions