Introduction
The Account Aggregator API is India’s most sophisticated financial data exchange infrastructure, but it is also one of the more complex integrations a fintech developer will encounter. The complexity is justified; the framework needs to handle consent management, cryptographic signing, multi-FIP data routing, and error handling across a distributed financial system.
This guide provides a practical technical overview of what AA API integration involves, from FIU registration to sandbox testing to production deployment. It is aimed at developers and product managers at fintechs and lending institutions building on the AA ecosystem. To understand the broader system context, here’s what an account aggregator is in India.
Overview of the Technical Architecture
The AA API ecosystem uses a RESTful API design, with endpoints defined by the Sahamati network’s API specification. The specification defines request-response contracts for consent requests, consent artefact management, data sessions, and data fetch operations. These specifications are defined within the Sahamati AA API documentation.
Key components include:
- Consent management API
- Data session API
- Notification webhook
- Cryptographic key infrastructure
The critical security requirement is your cryptographic key pair: the FIU’s public key is shared with FIPs, and the private key is used to decrypt received data securely.
AA Ecosystem and Participants
The AA ecosystem consists of three key entities:
- FIP (Financial Information Provider): Holds the financial data
- FIU (Financial Information User): Requests and consumes the data
- AA (Account Aggregator): Manages consent and routes encrypted data
To understand how these entities interact in detail, refer to FIP vs FIU roles in the account aggregator ecosystem.
Step 1: FIU Registration with an AA Operator
To begin integration, your institution must register as an FIU with a licensed AA operator. Options include Finvu, Onemoney, CAMS Finserv, and others. Working through a technology partner like Fineye provides access to AA infrastructure without requiring direct registration with multiple AA operators.
The registration process involves entity registration (confirming your regulated status), commercial agreement execution, submission of technical documentation (API endpoints, public key, and webhook URL), and completion of the operator’s sandbox onboarding.
These integrations must comply with the Reserve Bank of India’s Guidelines for Account Aggregators.
Most AA operators have a developer sandbox environment that provides test data and simulated FIP responses, allowing integration testing without live borrower data.
Step 2: Consent API Integration
The consent flow is the most complex part of the integration. The key API calls are:
POST /Consent: Initiate a consent request. Parameters include customer ID (the borrower’s mobile number linked to the AA), data types requested, date range, purpose, data life, and consent expiry. Response includes a consent handle.
GET /Consent/{consentHandle}: Poll consent status. Returns PENDING (awaiting borrower action), ACTIVE (borrower approved), REJECTED, EXPIRED, or REVOKED.
Webhook callback: Configure your server to receive real-time consent status updates via the notification URL registered with the AA operator.
The borrower reviews the request and authorizes data sharing. This aligns with the Digital Personal Data Protection Act, 2023.
To understand the mechanics behind this, refer to the account aggregator consent flow.
Handle each consent status appropriately in your application: show appropriate UX for pending states, proceed to data session initiation on ACTIVE status, and handle rejection or failure with appropriate fallback logic (PDF request or manual processing queue).
Step 3: Data Session and Data Fetch
Once a consent is in ACTIVE status, initiate a data fetch session:
POST /Sessions: Create a data session using the consent ID. Parameters include the specific date range and data type. Response includes a session ID.
GET /Sessions/{sessionId}: Poll session status. Returns PENDING, PARTIAL, DELIVERED, or FAILED.
GET /FI/fetch/{sessionId}: Retrieve the actual financial data once the session is DELIVERED. The response contains encrypted financial information objects from each FIP.
The encrypted data objects must be decrypted using your registered private key. The decrypted content conforms to the Sahamati Financial Information schema, a defined JSON structure for each financial information type (savings account, current account, term deposit, etc.).
Your analysis engine then processes the decrypted structured data to produce the credit intelligence output. To understand how this end-to-end data flow works in practice, here’s how the account aggregator works step-by-step.
Step 4: Key Management and Security Requirements
The security of your AA integration depends critically on your key management practices:
Key generation: Generate an RSA or ECDH key pair conforming to the Sahamati specification. Register the public key with your AA operator.
Private key security: The private key must never be stored in plaintext or in an insecure location. Use a managed key vault (AWS KMS, Azure Key Vault, or HashiCorp Vault) or HSM for production environments.
Key rotation: Implement a regular key rotation schedule. The Sahamati API supports key updates without service interruption if implemented correctly.
Audit logging: Log all consent events, data session initiations, and data fetch operations with timestamps and relevant identifiers. These logs are required for compliance audits and incident investigation.
Step 5: Error Handling and Resilience
AA integration must handle several error scenarios gracefully:
FIP unavailability: If a FIP is temporarily offline, data sessions will return PARTIAL or FAILED status. Implement retry logic with appropriate backoff intervals.
Consent timeout: Borrowers who do not act on consent requests within the session window will result in EXPIRED consent status. Design your UX to handle re-consent prompts.
Partial data delivery: When a borrower has accounts at multiple FIPs and some FIPs respond while others fail, the session returns PARTIAL status. Decide whether to proceed with partial data or wait for the full dataset.
Invalid consent artefact: If the consent is revoked between session initiation and data delivery, the session will fail. Handle this as a consent-required re-entry in your loan application flow.
Key Takeaways
- AA API integration requires FIU registration with a licensed AA operator, cryptographic key infrastructure, consent API integration, data session management, and robust error handling.
- Working through a technology partner (like Fineye) provides access to AA infrastructure without direct multi-operator registration, significantly reducing the integration timeline.
- The consent API is the most complex component: building a robust consent state machine with webhook support, retry logic, and appropriate user experience for each consent state is essential.
- Teams must treat private key security as non-negotiable and store keys in a key vault or HSM. They must never store private keys in plaintext application storage.
- Teams should thoroughly complete sandbox testing with simulated FIP responses before production deployment. They must handle diverse production error states gracefully.
Frequently Asked Questions
A direct integration with a single AA operator typically takes 6–12 weeks, including FIU registration, sandbox development and testing, security review, and production go-live. Working through a technology partner with pre-built AA infrastructure can reduce this to 2–4 weeks.
Yes. The Sahamati API specification is publicly available on Sahamati’s GitHub repository. Developers can review the full API contract, data schemas, and error codes before beginning integration.
The AA API is language-agnostic; teams can use any language that supports REST calls and cryptographic operations. Common choices include Python, Java, Node.js, and Go.
Yes. Integrating with multiple AA operators improves redundancy and coverage. Each operator requires a separate FIU registration and API integration. Most fintechs start with one operator and add others as the ecosystem matures.
Use the sandbox environments provided by AA operators. These provide simulated borrower profiles, FIP responses, and error scenarios. Fineye’s sandbox provides additional pre-built test scenarios, including multi-account data flows and error state simulation.
Conclusion
AA API integration requires significant engineering effort, but teams can execute it with a clear, well-defined process. The Sahamati API specification is comprehensive, documents error states, and supports thorough sandbox testing.
The choice between direct integration and using a partner depends on your engineering capacity and timelines. A well-executed integration not only enables secure data access but also unlocks real-time financial intelligence for decision-making. This is exactly how account aggregator reduces loan processing time, transforming both speed and efficiency in digital lending.
