OMSAA API Documentation

Powering the Future of Open Finance

OMSAA (Account Aggregator) provides a robust API ecosystem that enables secure, user-consented, and seamless data exchange between Financial Information Providers (FIPs) and Financial Information Users (FIUs). Our infrastructure transforms fragmented financial data into actionable intelligence, empowering organizations to build superior financial products with trust, security, and transparency.

Key Capabilities

Unified Financial ProfilesAggregate data from multiple sources to create a 360-degree view.
Precision UnderwritingElevate credit assessments with real-time, verified transaction data.
Intelligent PFMBuild personal finance management tools with automated insights.
Frictionless OnboardingSimplify data sharing for underserved markets.

Getting Started with OMSAA

The Account Aggregator (AA) framework is a revolutionary financial data-sharing system that enables individuals and businesses to securely share their financial information with trusted third parties.

As an RBI-regulated framework, OMSAA acts as a secure, digital bridge between Financial Information Providers (FIPs) and Financial Information Users (FIUs). We eliminate the need for physical documents and manual uploads, replacing them with a seamless, encrypted digital data flow that ensures trust, transparency, and compliance.

Why Choose the OMSAA Ecosystem?

Integration Path

  1. Register as an FIU: Obtain your API credentials and sandbox access through the OMSAA Developer Portal.
  2. Configure Webhooks: Set up secure endpoints to receive real-time notifications for consent status updates and data readiness events.
  3. Initiate Consent: Use OMSAA Consent APIs to trigger a consent request directly to your customer’s registered mobile device.
  4. Fetch & Decrypt Data: Upon customer approval, leverage the Data Journey APIs to fetch encrypted financial data packets and decrypt them securely within your environment.

The Architecture at a Glance

To help your team visualize how OMSAA fits into the broader financial ecosystem, refer to the technical flow below:

OMSAA Technical Flow Architecture Diagram

OMSAA API Sequence & Integration Flow

The following outlines the standardized sequence required to integrate with the OMSAA Account Aggregator ecosystem. This flow ensures a secure, RBI-compliant, and frictionless data-sharing experience.

1. Consent Lifecycle

Consent Initiation The FIU triggers a POST /Consent request to OMSAA, defining the purpose, validity, and fetch frequency.
Handshake OMSAA responds with a ConsentHandle, a unique reference used to track the request progress.
User Authorization The customer uses the OMSAA interface to discover bank accounts (FIPs) and grant explicit consent.
Consent Notification Once approved, OMSAA pushes a POST /Consent/Notification to the FIU's webhook with the consentId.
Artifact Retrieval The FIU fetches the signed consent artifact by sending a POST /Consent/fetch request.

2. Secure Data Orchestration

Initiating the Session The FIU sends a POST /FI/request with the consentId and KeyMaterial to generate a sessionId.
FIP Communication OMSAA relays the request to the FIP. The FIP acknowledges and prepares the encrypted data packet.
Data Readiness The FIP notifies OMSAA, which triggers a POST /FI/Notification to the FIU signaling data is ready.
The Final Fetch The FIU executes a POST /FI/fetch using the sessionId to receive the encrypted financial data.

Integration Security & Features

The OMSAA ecosystem is built on the foundation of trust and technical excellence, ensuring that every data exchange is secure and auditable.

Feature Description
Traceability ConsentHandle and ConsentId ensure every transaction is uniquely identifiable and auditable across the network.
Session Persistence The SessionID securely links data fetch requests to specific user-approved consent artifacts, maintaining state throughout the data journey.
End-to-End Security Utilizes Diffie-Hellman Key Exchange and robust encryption, ensuring OMSAA never sees the raw data; we only facilitate the secure transit.
Privacy by Design Data is shared strictly on a "need-to-know" basis, governed by the duration and frequency set by the user during the authorization phase.

Technical Prerequisites

Before initiating your first API call, ensure your environment meets these three security requirements to ensure RBI compliance and data integrity.

1. Client Authentication
You must possess a valid client_api_key issued via the Sahamati Token Service. This token identifies your entity and must be present in the header of every request.
2. Request Signing (JWS)

To ensure non-repudiation and data integrity, every request and response must be signed using a JSON Web Signature (JWS) with a detached payload.

  • The signature must be included in the x-jws-signature HTTP header.
  • Refer to the Sahamati Tools for implementation libraries (Java, Node.js, Python).
3. Obtaining your Client API Token

Follow the OAuth 2.0 flow to retrieve your credentials from the Sahamati Central Registry (CR):

Parameter Value / Details
Token URL (UAT) https://uattokens.sahamati.org.in/.../token
Grant Type client_credentials
Auth Method Basic Auth (using your Client ID and Secret)

API Endpoints & Security

Configure your client to point to the appropriate environment and include the mandatory security headers for every request.

Service Environments
Environment Base URL
UAT (Testing) https://uat-app.omsaa.in
Production https://api.omsaa.in
Required Headers
Header Key Description / Expected Value
Content-Type application/json
client_api_key Your unique Bearer token from Sahamati
x-jws-signature Detached JWS signature of the request body.
Required for all POST operations.

Data Request

POST /FI/request

This API is used by the FIU to request for financial information from the AA. The AA will validate the request against the signed consent and return a sessionID which can then be used by the FIU to fetch the required data.

REQUEST BODY 
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "e8cc6822-d4bb-4eb1-9e1b-4996fbff8acb",
  "FIDataRange": {
    "from": "2023-07-06T11:39:57.153Z",
    "to": "2019-12-06T11:39:57.153Z"
  },
  "Consent": {
    "id": "654024c8-29c8-11e8-8868-0289437bf331",
    "digitalSignature": "NdjwMjLortTb10dxcJezkvdOxPVvEdZvIqwqVWOHnE8pS_YDswcRPLTRmds2xO-Tvm_A2cFv1qKYpaZnv8Bl
    6xmZoOsG_F8_40gRZqIhz5hF9puzp8lEEhMlZ6NaX2Y2OYkwHcOBBpCIXpLXB4CMWiefUEWjO9zKDd5JJwZ4vLWeT4qgwvPfRqE60B33t
    zVlF5E6OA2mKK17sGRXsfrI9obEjL52RMdGo_9bv1HnHfvPlbj5ihj6d_5iTtoh7HUC_X8CrJGvkgkCjP_7of1jPb5QgJ9nx_Yfsxj3vf
    8zEseZIVISjF3MwBzW7Di4CpfQl4wlnpkQO9MKu78F69Z9Ig"
  },
  "KeyMaterial": {
    "cryptoAlg": "ECDH",
    "curve": "Curve25519",
    "params": "cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH",
    "DHPublicKey": {
      "expiry": "2023-07-06T11:39:57.153Z",
      "Parameters": "string",
      "KeyValue": "string"
    },
    "Nonce": "29512b70-ca84-46b5-9471-63765599cf15"
  }
}
RESPONSE
200 OK
{
  "ver": "2.0.0",
  "timestamp": "2023-06-2611:39:57.153Z",
  "txnid": "e8cc6822-d4bb-4eb1-9e1b-4996fbff8acb",
  "consentId": "654024c8-29c8-11e8-8868-0289437bf331",
  "sessionId": "caa2f259-2dc2-4075-87aa-6d81018b6183"
}
POST /FI/fetch

This API is used to fetch financial information from AA once FIU recieves the data ready notification.

REQUEST BODY 
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "3dd436f8-0747-4a8f-9001-375e419430be",
  "sessionId": "caa2f259-2dc2-4075-87aa-6d81018b6183",
  "fipId": "FIP-1",
  "linkRefNumber": [
    {
      "id": "XXXX-XXXX-XXXX"
    }
  ]
}
RESPONSE
200 OK
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "3dd436f8-0747-4a8f-9001-375e419430be",
  "FI": [
    {
      "fipID": "FIP-1",
      "data": [
        {
          "linkRefNumber": "XXXX-XXXX-XXXX",
          "maskedAccNumber": "XXXXXXXX4020",
          "encryptedFI": "string"
        }
      ],
      "KeyMaterial": {
        "cryptoAlg": "ECDH",
        "curve": "Curve25519",
        "params": "cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH",
        "DHPublicKey": {
          "expiry": "2023-07-06T11:39:57.153Z",
          "Parameters": "string",
          "KeyValue": "string"
        },
        "Nonce": "29512b70-ca84-46b5-9471-63765599cf15"
      }
    }
  ]
}

Notifications

POST /Consent/Notification

This API can be used by AA Client, FIU and FIP to place a request for consent status update to AA in specific use cases. For more details, please refer FAQ section.

REQUEST BODY 
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
  "Notifier": {
    "type": "FIP",
    "id": "FIP-1"
  },
  "ConsentStatusNotification": {
    "consentId": "XXXX0-XXXX-XXXX",
    "consentStatus": "REJECTED"
  }
}
RESPONSE
200 OK
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:13:30.967+0000",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "response": "OK"
}
POST /FI/Notification

This API can be used by AA Client, FIU and FIP to send notifications related to Financial Information (FI) fetch to AA.

REQUEST BODY 
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
  "Notifier": {
    "type": "FIP",
    "id": "FIP-1"
  },
  "FIStatusNotification": {
    "sessionId": "XXXX0-XXXX-XXXX",
    "sessionStatus": "ACTIVE",
    "FIStatusResponse": [
      {
        "fipID": "FIP-1",
        "Accounts": [
          {
            "linkRefNumber": "XXXX-XXXX-XXXX",
            "FIStatus": "READY",
            "description": ""
          }
        ]
      }
    ]
  }
}
RESPONSE
200 OK
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:13:30.967+0000",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "response": "OK"
}
POST /Account/link/Notification

This API can be used by FIP to send account linking related notifications to AA in case of direct authentication method of account linking.

REQUEST BODY 
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
  "Notifier": {
    "type": "FIP",
    "id": "FIP-1"
  },
  "AccountLinkStatusNotification": {
    "accRefNumber": "XXXX0-XXXX-XXXX",
    "customerAddress": "customer_identifier@aa_identifier",
    "linkRefNumber": "XXXX-XXXX-XXXX",
    "linkStatus": "LINKED"
  }
}
RESPONSE
200 OK
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:13:30.967+0000",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "response": "OK"
}

Monitoring

GET /Heartbeat

This API can be used by FIPs and FIUs to check availability of AA Application.

RESPONSE
200 OK
{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "Status": "UP",
  "Error": {
    "code": 0,
    "msg": "string",
    "detail": "string"
  }
}