DocumentationHybrid Experience

Account Aggregator Flow

Some lenders need Account Aggregator consent before they can return a final or actionable offer. Hybrid Experience exposes that requirement through the offers polling API, so your product can show the borrower the right consent action without building the Account Aggregator journey yourself.

Your product remains in control of the borrower UI until offer selection. Aarthik Labs creates the Account Aggregator handoff URL, tracks the consent session, receives the callback, reconciles lender state, and continues offer orchestration after the borrower returns.

Where AA Fits In Hybrid

Account Aggregator appears during offer discovery, before Hosted handoff.

Your app does not call a separate customer-facing Account Aggregator API. The offers endpoint tells you when AA is needed and gives you the short-lived URL to open.

When AA Appears

Your back-end discovers Account Aggregator readiness while polling:

GET /api/v1/hybrid/personal-loan/borrowers/{borrowerProviderID}/journey/offers

If the response includes data.account_aggregator.status = READY, your app can show a borrower-facing action such as “Continue with bank statement consent” and open data.account_aggregator.url.

If the response includes data.account_aggregator.status = PROCESSING, your app should keep the borrower in a waiting state and poll again after poll_after_ms.

If data.account_aggregator is not present, there is no actionable AA step for your product at that moment. Continue rendering offers, waiting states, or terminal states from the rest of the response.

AA Statuses

StatusMeaningWhat your app should do
READYA short-lived Account Aggregator URL is available.Ask the borrower to continue and open data.account_aggregator.url immediately.
PROCESSINGThe platform is preparing consent, waiting for callback completion, or reconciling lender state after the borrower returns.Keep showing a wait state and poll again after poll_after_ms.

The AA URL is short-lived. If the borrower returns later or the URL expires, call the offers endpoint again and use the latest URL.

Response Shape

When AA is ready, the offers response includes an account_aggregator object:

1{
2  "data": {
3    "status": "OFFERED",
4    "account_aggregator": {
5      "available": true,
6      "status": "READY",
7      "url": "https://credit.aarthiklabs.com/lab/account-aggregator?token=...",
8      "expires_at": "2026-04-08T01:26:10.000Z",
9      "lenders": ["AA Bank"],
10      "poll_after_ms": 3000
11    },
12    "lenders": {
13      "AA Bank": {
14        "accountAggregatorURL": "https://credit.aarthiklabs.com/lab/account-aggregator?token=...",
15        "offers": [
16          {
17            "status": "OFFER_AWAITED",
18            "consentHandleAvailable": true,
19            "offerID": null
20          }
21        ]
22      }
23    }
24  },
25  "error": null
26}

Important fields:

FieldMeaning
data.account_aggregator.statusWhether the borrower can act now (READY) or should keep waiting (PROCESSING).
data.account_aggregator.urlShort-lived hosted AA URL. Present only when status is READY.
data.account_aggregator.expires_atExpiry time for the returned URL. Present when url is present.
data.account_aggregator.lendersBorrower-visible lender names that currently need AA consent.
data.account_aggregator.poll_after_msRecommended delay before the next offers poll.
data.lenders.<name>.accountAggregatorURLConvenience copy of the same URL for the related lender group.

If the response also includes normal OFFER_RECEIVED offers, your UI can show those offers while also giving the borrower the option to complete AA for additional lender responses.

Borrower Flow

What Your Product Should Build

Your product should build only the borrower-facing control points:

  • show a clear consent call-to-action when status = READY
  • open the latest returned url immediately
  • keep the borrower in a wait state when status = PROCESSING
  • poll again using poll_after_ms
  • refresh offers after the borrower returns from consent
  • handle URL expiry by polling for a fresh URL
  • preserve already available offers while AA-backed lenders are still processing

Your product should not:

  • create or complete AA sessions directly
  • modify the AA URL
  • store the AA URL as a long-term resume link
  • expose the platform API key to the front-end
  • assume that every lender requires AA
  • assume that AA always produces an offer

How The Platform Handles AA

Behind the scenes, Aarthik Labs treats Account Aggregator as a sessionized flow:

  • the platform records lender consent requirements for the borrower journey
  • if multiple lenders need consent, the platform can consolidate eligible consent handles into one borrower AA run
  • the borrower completes consent through the hosted Account Aggregator surface
  • the callback completes the AA session
  • the platform dispatches approval or reconciliation back into lender orchestration
  • the offers endpoint reflects updated offer state once lenders respond

Your product does not need to model these internal sessions. It only needs to react to the polling response and open the returned AA URL when it is ready.

Offer Display With AA

The offers response can contain both immediate offers and lenders waiting for AA.

Your UI can:

  • show ready OFFER_RECEIVED offers immediately
  • show an Account Aggregator call-to-action when AA can unlock more lender responses
  • keep waiting for AA-backed lenders while preserving already available offers
  • refresh the offer list after the borrower returns from consent

Do not block the borrower from selecting an already available offer unless your own product policy requires waiting for all lender responses.

Return And Polling Behavior

After the borrower completes or exits the Account Aggregator surface, your app should return the borrower to your Hybrid UI and poll offers again.

Use this decision model:

SituationRecommended behavior
Borrower completed consentPoll offers again. Show a waiting state while lenders reconcile.
Borrower closed or exited consentPoll offers again. If AA is still required, show the consent action again when a fresh URL is ready.
URL expired before openingPoll offers again and use the latest URL.
PROCESSING continues for a whileKeep the borrower informed and continue polling with poll_after_ms.
No offer is available after reconciliationShow your no-offer state from the offers response.

The Account Aggregator callback and lender reconciliation are asynchronous. A successful borrower return does not always mean offers are immediately ready on the next poll.

Mobile App Handling

If your Hybrid journey runs inside a mobile app, open the AA URL in a browser or app-controlled surface that can preserve session state and return the borrower to your product.

Your mobile app should:

  • keep the Aarthik Labs API key server-side
  • open the AA URL without modifying it
  • allow the borrower to return to your Hybrid UI after consent
  • continue polling offers from your back-end after the borrower returns
  • support the same browser capabilities documented in the Hybrid mobile application guide

Read Mobile App Bridge and Mobile App Permissions for mobile-specific handling.

Some lender flows may also require monitoring consent after an offer path has progressed. The borrower-facing handling is similar: the platform prepares an Account Aggregator URL, the borrower completes consent in the hosted surface, and Aarthik Labs reconciles the callback before continuing lender progression.

For most Hybrid integrations, the most important AA behavior is pre-offer consent because it can unlock lender responses before the borrower selects an offer. Monitoring consent is handled later by the platform-managed journey surface when it applies.

Error And Retry Handling

Design your UI so AA failures do not trap the borrower.

CaseRecommended behavior
AA URL is missing while PROCESSINGKeep waiting and poll again after poll_after_ms.
AA URL fails to openShow a retry action and poll for a fresh URL.
Borrower abandons consentReturn to your Hybrid UI and let the offers response decide the next action.
Lender does not return an offer after AAShow the lender state or no-offer state from the offers response.
Browser or webview blocks the AA surfaceMove the borrower to a supported browser surface and retry with a fresh URL.

Implementation Checklist

Your integration should:

  • show Account Aggregator only when the API returns an actionable AA state
  • open the latest returned AA URL immediately
  • support browser or mobile webview behavior required for external consent screens
  • poll again after the borrower returns
  • keep the borrower in a clear waiting state while AA is processing
  • avoid storing AA URLs as long-term resume links
  • log journey ID, borrower provider ID, AA status, and lender names for support
  • avoid logging full AA URLs unless your internal policy explicitly allows it