Account Aggregator - FI Request API

This document highlights the Account Aggregator - FI Request API details.

API Description

Objective

The Account Aggregator - FI Request API decrypts the response from the Account Aggregator, verifies the consent status, and triggers a data request for user's Financial Information.

API URL

https://ind-engine.thomas.hyperverge.co/v1/AAFIRequest

API Endpoint

AAFIRequest

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table outlines the parameter required in the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
consentHandle	Mandatory	A unique value for tracking and retrieving user data in the verification journey	Not Applicable	Not Applicable
custId	Mandatory	The 10 digit contact number of the User	Not Applicable	Not Applicable
encryptedFiuId	Mandatory	The encrypted identifier for the Financial Information User (FIU)	Base64-encoded string	Not Applicable
encryptedRequest	Mandatory	The Base64-encoded and encrypted request parameters	Base64-encoded string	Not Applicable
numberOfMonths	Mandatory	The duration for which data is requested	Numeric value representing months	Not Applicable
requestDate	Mandatory	The request timestamp in UTC, formatted as ddmmyyyyhhmmsss	Numeric value in ddmmyyyyhhmmsss format	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/AAFIRequest' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "consentHandle": "<Consent_Handle_From_First_API_Call>", 
    "custId": "<User_Mobile_Number>", 
    "encryptedFiuId": "<Encrypted_FiuId_From_First_API_Call>", 
    "encryptedRequest": "<Encrypted_Request_From_First_API_Call>", 
    "numberOfMonths": "<Number_Of_Months_As_String>", 
    "requestDate": "<Request_Date_From_First_API_Call>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "metaData": {
    "requestId": "<Unique_Request_ID>"
  },
  "result": {
    "consentStatus": "<Consent_Status>",
    "AAWebviewDecrypt": {
      "statusCode": "200",
      "response": {
        "header": {
          "rid": "<Unique_Request_ID>",
          "ts": "<Timestamp_in_ISO_Format>",
          "channelId": "<Channel_ID>"
        },
        "body": {
          "txnId": "<Transaction_ID>",
          "sessionId": "<Session_ID>",
          "srcRef": "<Source_Reference_ID>",
          "userId": "<User_ID>",
          "redirectUrl": "<Redirect_URL>",
          "fiuId": "<FIU_ID>",
          "status": "<Status>",
          "errorCode": "<Error_Code>",
          "email": "<Email>",
          "pan": "<PAN_Number>",
          "dob": "<Date_Of_Birth_in_DD-MM-YYYY_Format>",
          "fip": "<FIP_Details>"
        }
      }
    },
    "AAConsentStatus": {
      "statusCode": "200",
      "response": {
        "header": {
          "rid": "<Unique_Request_ID>",
          "ts": "<Timestamp_in_ISO_Format>",
          "channelId": "<Channel_ID>"
        },
        "body": {
          "consentStatus": "<Consent_Status>",
          "consentId": "<Consent_ID>"
        }
      }
    },
    "AAFIRequest": {
      "statusCode": "200",
      "response": {
        "header": {
          "rid": "<Unique_Request_ID>",
          "ts": "<Timestamp_in_ISO_Format>",
          "channelId": "<Channel_ID>"
        },
        "body": {
          "ver": "<Version>",
          "timestamp": "<Timestamp_in_ISO_Format>",
          "txnid": "<Transaction_ID>",
          "consentId": "<Consent_ID>",
          "sessionId": "<Session_ID>",
          "consentHandleId": "<Consent_Handle_ID>"
        }
      }
    }
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
statusCode	integer	The HTTP status code of the response
success	string	The success status of the request
requestId	string	A unique identifier for the request
consentStatus	string	The status of the consent request
txnId	string	A unique transaction identifier
sessionId	string	The session identifier for the transaction
srcRef	string	A reference identifier for the transaction source
userId	string	The unique user identifier associated with the request
redirectUrl	string	The URL to redirect the user for further processing
fiuId	string	The FIU identifier
status	string	The status of the transaction
errorCode	string	The error code if the request fails
email	string	The email address associated with the user
pan	string	The Permanent Account Number (PAN) of the user
dob	string	The date of birth of the user
fip	string	The Financial Information Provider (FIP) identifier
consentId	string	A unique identifier for the consent request
ver	string	The version of the API response
timestamp	string	The timestamp of the API response
txnid	string	A unique identifier for the transaction
consentHandleId	string	A unique identifier for the consent handle