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 Personal Loans, append isOfferAccepted=true only after your application has captured the borrower’s explicit acceptance. The parameter accepts only the exact lowercase values true and false; invalid supplied values return INVALID_IS_OFFER_ACCEPTED without accepting the offer.

Omitting the parameter or sending false returns the standard Hosted offer and KFS review flow. A true request returns offer_acceptance; check offer_acceptance.applied rather than assuming acceptance was applied. When it is false, open the returned hosted_url for the standard Hosted review. When it is true, use the polling fields until the lender step is ready.

When offer_acceptance.applied is true, the idempotent call returns one of these pollable outcomes:

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 a READY URL automatically forwards the borrower to the lender’s current step. 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. A brief blank loading page may appear while the URL is validated.

Bank mandate remains Hosted when the borrower action belongs to Aarthik Labs or must be completed locally. Omitted or false acceptance calls preserve the standard Hosted experience. If a direct handoff cannot be completed, request a fresh hosted_url; do not ask the borrower to share the complete Hosted URL or its fragment.

Supported LAMF opt-in 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 Hybrid, the selected row can have productType: BUSINESS_LOAN or productType: PERSONAL_LOAN. In both cases, send the BUSINESS_LOAN public Business root as journeyID. Acceptance and stage reads use the offer’s real source journey, while the response keeps data.target_journey_id and data.journey.id equal to that public root. data.journey.type and data.journey.offer.productType identify the selected product, and companion source IDs remain internal.

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.

1
{
2
  "data": {
3
    "hosted_url": "https://credit.aarthiklabs.com/lab/handoff?handoff=...",
4
    "expires_at": "2026-05-14T09:16:30.000Z",
5
    "target_offer_id": "offer_gl_001",
6
    "target_branch_id": "branch_001",
7
    "target_journey_id": "journey_gl_001",
8
    "journey": {
9
      "type": "GOLD_LOAN",
10
      "status": "OFFERED",
11
      "lender": {
12
        "id": "lender_001",
13
        "lender_name": "Gold Lender",
14
        "lender_gro_name": "Support Lead",
15
        "lender_gro_email": "gro@example.com",
16
        "lender_customer_support_contact_number": "1800123456"
17
      },
18
      "offer": {
19
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
20
        "accepted": false,
21
        "expired": false,
22
        "amountPrincipal": "400000",
23
        "amountTotalInterestPayable": "42300",
24
        "amountNetDisbursedAmount": "392000",
25
        "offerTerm": "5 months",
26
        "interestRate": "12.00",
27
        "interestType": "FIXED",
28
        "annualPercentageRate": "5.00",
29
        "numberOfInstallments": 5,
30
        "coolOffPeriod": "3 days",
31
        "termsAndConditionsLink": "https://example.com/tnc.pdf",
32
        "keyFactsStatementLink": "https://example.com/kfs.pdf",
33
        "applicationFees": "0",
34
        "foreclosureFees": "0",
35
        "interestRateConversionCharges": "0",
36
        "delayPenaltyFees": "0",
37
        "otherPenaltyFees": "0",
38
        "processingFees": "8000",
39
        "otherUpfrontCharges": "0",
40
        "insuranceCharges": "0",
41
        "otherCharges": "0",
42
        "installments": [
43
          {
44
            "serialNumber": 1,
45
            "type": "INSTALLMENT",
46
            "amount": "12000.00",
47
            "status": "PAID | OVERDUE | NOT-DUE",
48
            "dueDate": "2024-08-01"
49
          }
50
        ],
51
        "relationshipManager": {
52
          "name": "Rajesh Sharma",
53
          "phone": "+91-9876543210"
54
        }
55
      }
56
    }
57
  }
58
}

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