Skip to content
by Rakesh Waghela

5.15 AA technical protocol detail

This page is the technical detail of the Account Aggregator integration. Business context and rules are in 2.8 AA rules; vendor selection in 4.3.

The authoritative AA specifications are published by ReBIT (Reserve Bank Information Technology) at api.rebit.org.in. Implementations evolve; always cross-reference the current version before building.

Roles recap

Section titled “Roles recap”
  • FIP — Financial Information Provider (the bank / mutual fund / etc.).
  • AA — Account Aggregator (NBFC-AA licensed by RBI).
  • FIU — Financial Information User (your lending platform).
  • TSP — Technology Service Provider that gives the FIU an SDK / API to interact with multiple AAs.

For most lenders, the TSP abstracts the multi-AA complexity; the FIU app speaks one API (the TSP’s) and the TSP speaks to AAs.

Integration shape

Section titled “Integration shape”
                ┌─────────────────────────────┐
                │  Lending Platform (FIU)     │
                └──────────────┬──────────────┘
                               │ FIU SDK / API
                               ▼
                ┌─────────────────────────────┐
                │  TSP (Setu / FinBox / etc.)  │
                └─────┬─────────┬─────────────┘
                      │         │
              ┌───────▼──┐  ┌───▼─────┐
              │  AA 1     │  │  AA 2   │ ... (multi-AA)
              │ (Finvu)   │  │ (Saafe) │
              └───────────┘  └─────────┘
                      │         │
              ┌───────▼─────────▼───────┐
              │      FIP 1, FIP 2 ...   │
              │  (HDFC, ICICI, SBI ...) │
              └─────────────────────────┘
Section titled “Consent lifecycle”

Five states:

  • REQUESTED — FIU has requested consent; borrower not yet acted.
  • ACTIVE — borrower granted; consent valid; data fetches permitted.
  • PAUSED — temporarily suspended (rare).
  • REVOKED — borrower revoked.
  • EXPIRED — validity period elapsed.
Section titled “Consent request”

FIU initiates a consent request via TSP. Key parameters:

{
  "consent_purpose": {
    "code": "101",
    "text": "Wealth management service",
    "ref_uri": "https://api.rebit.org.in/aa/purpose/101.xml",
    "category": {
      "type": "Loan Application"
    }
  },
  "fi_types": ["DEPOSIT", "TERM_DEPOSIT"],
  "consent_types": ["TRANSACTIONS", "PROFILE", "SUMMARY"],
  "data_fetch_frequency": {
    "unit": "MONTH",
    "value": 1
  },
  "data_life": {
    "unit": "YEAR",
    "value": 1
  },
  "data_range": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2026-05-01T00:00:00Z"
  },
  "consent_expiry": "2027-05-01T00:00:00Z",
  "fi_data_range_max_per_fetch": "365D",
  "customer": {
    "id": "9876543210@finvu"   // borrower's AA handle
  },
  "fips": ["HDFC", "ICICI"]   // optional; if known
}

The AA generates a consent handle and provides the borrower a consent screen (web or app). The borrower:

  1. Authenticates with the AA (mobile + OTP).
  2. Reviews the consent parameters (purpose, FI types, frequency, data range, validity).
  3. Selects which accounts at which FIPs to link.
  4. Approves → AA generates consent artefact.
Section titled “Consent artefact”

The signed consent artefact (JWS / JWT-like) contains:

  • Issuer: the AA.
  • Borrower’s AA handle.
  • FIU’s identifier.
  • All parameters from the request.
  • AA’s signature (verifiable).
  • Issued-at + expiry.

The FIU stores the artefact as evidence — auditable, tamper-evident.

CREATE TABLE aa_consent (
    id BIGSERIAL PRIMARY KEY,
    borrower_id BIGINT NOT NULL,
    consent_handle VARCHAR(128) NOT NULL UNIQUE,
    artefact_signed TEXT NOT NULL,
    artefact_decoded_json JSONB NOT NULL,
    aa_name VARCHAR(64) NOT NULL,
    status VARCHAR(16) NOT NULL DEFAULT 'requested',
    purpose VARCHAR(128) NOT NULL,
    fi_types TEXT[] NOT NULL,
    data_range_start TIMESTAMPTZ NOT NULL,
    data_range_end TIMESTAMPTZ NOT NULL,
    fetch_frequency VARCHAR(64) NOT NULL,
    valid_from TIMESTAMPTZ NOT NULL,
    valid_to TIMESTAMPTZ NOT NULL,
    revoked_at TIMESTAMPTZ
);

FI data request (fetch)

Section titled “FI data request (fetch)”

Once consent is active, the FIU triggers a fetch:

{
  "consent_id": "consent-uuid",
  "consent_handle": "consent-handle",
  "fi_data_range": {
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-05-01T00:00:00Z"
  },
  "key_material": {
    "crypto_alg": "ECDH",
    "curve": "Curve25519",
    "params": "...",
    "dh_public_key": {
      "expiry": "...",
      "public_key": "..."
    }
  }
}

The FIU provides ECDH public key material for end-to-end encryption (FIP → FIU; AA doesn’t decrypt the data).

The AA returns a session ID while the AA orchestrates fetch from FIP.

FI data response

Section titled “FI data response”

When data is ready, FIU polls or receives a webhook:

{
  "session_id": "fetch-session-uuid",
  "data": [
    {
      "fip_id": "HDFC",
      "data": [
        {
          "link_ref_number": "...",
          "masked_account_number": "XXXXXX1234",
          "encrypted_fi": "..."   // ECDH-encrypted; FIU decrypts using its private key
        }
      ]
    }
  ]
}

The FIU decrypts each encrypted_fi using its private key (paired with the public key it sent). Decrypted payload is the FI data XML (per ReBIT FI-type-specific schema).

DEPOSIT FI type — what’s in the data

Section titled “DEPOSIT FI type — what’s in the data”

For a DEPOSIT account, FIP returns:

  • Account summary: account holder name, account type, IFSC, current / available balance, currency, account opening date, ATM card status.
  • Account profile: full holder details.
  • Account transactions: per transaction — date, narration, amount, debit / credit, balance after, reference number, mode (UPI / NEFT / etc.).

XML schema (illustrative; full schema in ReBIT):

<Account>
  <Profile>
    <Holders type="SINGLE">
      <Holder name="Sundar Textiles Pvt Ltd" .../>
    </Holders>
  </Profile>
  <Summary
    type="CURRENT"
    branch="HDFC Mumbai Main"
    facility="OD"
    status="ACTIVE"
    ifscCode="HDFC0001234"
    currentBalance="185000.45"
    currency="INR"
    drawingLimit="0.00"
    pending_amount="0.00"
    openingDate="2020-04-01"
  />
  <Transactions startDate="2025-05-01" endDate="2026-05-01">
    <Transaction
      type="CREDIT"
      mode="UPI"
      amount="5000.00"
      currentBalance="190000.45"
      transactionTimestamp="2026-04-15T10:23:45Z"
      txnId="..."
      narration="UPI/2026041510234/8765432101@oksbi/PAYMENT"
      reference="..."
    />
    <Transaction
      type="DEBIT"
      mode="NACH"
      amount="45000.00"
      currentBalance="145000.45"
      transactionTimestamp="2026-04-05T09:15:00Z"
      narration="NACH DR/HDFC/LOANEMI"
      ...
    />
    ...
  </Transactions>
</Account>

The FIU’s BSA layer parses this into the platform’s normalised model.

Multi-AA orchestration

Section titled “Multi-AA orchestration”

A borrower may have accounts across multiple FIPs, registered with different AAs. The TSP handles:

  • Routing consent requests to the right AA (based on FIP availability per AA).
  • Aggregating data from multiple AAs into a single response to the FIU.
  • Falling over if one AA is unavailable.

The FIU treats this as a single API; the complexity is in the TSP.

Periodic fetch

Section titled “Periodic fetch”

With consent’s data_fetch_frequency of MONTHLY, the platform’s scheduler triggers a fetch each month. Returns latest data within the original data_range or new range as permitted.

This is the monitoring data source for active borrowers (see 16.7 Continuous monitoring).

Revocation handling

Section titled “Revocation handling”

Borrower can revoke consent at the AA. The AA notifies the FIU via webhook:

{
  "consent_id": "...",
  "consent_status": "REVOKED",
  "revoked_at": "2026-06-15T..."
}

FIU action:

  • Mark consent as revoked.
  • Stop scheduled fetches.
  • Per DPDP, purge fetched data after the purpose period or immediately if revocation requires.
  • Log revocation.
Section titled “Consent expiry”

When valid_to is reached:

  • Consent transitions to EXPIRED.
  • FIU’s scheduler stops fetching.
  • For ongoing borrowers, the FIU initiates a re-consent flow.

Error handling

Section titled “Error handling”

Common error scenarios:

ScenarioAction
Borrower abandons AA consent screenMark consent REQUESTED; expire after timeout (e.g., 24 hours); follow-up nudge
AA returns error during fetchRetry with backoff; failover to alternate AA if multi-AA
FIP outage at AA’s endWait for FIP recovery; AA will eventually return data
Decryption failureLikely FIU key issue; regenerate keys; alert
Schema parsing failureFIP returned unexpected schema; log + investigate

Security

Section titled “Security”
  • All transport: TLS 1.2+ between FIU ↔ TSP ↔ AA ↔ FIP.
  • Payload encryption: end-to-end via ECDH; AA cannot decrypt FI data.
  • FIU’s private keys: managed in HSM / KMS; never exported.
  • Consent artefact verification: FIU verifies AA’s signature on the artefact before trusting.

Performance

Section titled “Performance”
  • Consent flow end-to-end: typically 3 – 7 minutes for borrower (depends on borrower interaction speed).
  • Data fetch: usually 1 – 10 minutes (FIP-dependent).
  • Volume: AA ecosystem handles tens of millions of consents and fetches per month.

What the FIU platform must build

Section titled “What the FIU platform must build”
  • AA consent service — initiate, status, revoke handling.
  • AA fetch service — trigger, poll, decrypt, store.
  • Multi-AA routing via TSP.
  • Consent artefact storage — immutable, audit-evidence-grade.
  • FI data normalisation — parse FIP XML into internal model.
  • Periodic fetch scheduler — for ongoing monitoring.
  • Revocation webhook handler.
  • Re-consent workflow at expiry.
  • DPDP-compliant retention — purge per consent’s data_life.

Compliance

Section titled “Compliance”
  • AA Master Direction (RBI).
  • DPDP Act 2023 — every fetch is personal data processing.
  • ReBIT specifications — protocol conformance.
  • Outsourcing MD — TSP and AA both governed.
Section titled “Related”