Account Aggregator - FI Data API

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

API Description

Objective

The Account Aggregator - FI Data API retrieves the final financial information record of the user from the Account Aggregator once the data request has been successfully processed.

API URL

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

API Endpoint

AAFIData

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
consentId	Mandatory	The unique identifier for the user's consent	Not Applicable	Not Applicable
sessionId	Mandatory	The unique session identifier	Not Applicable	Not Applicable
custId	Mandatory	The user identifier, typically a mobile number	Not Applicable	Not Applicable
transactionAmountThreshold	Optional	The threshold amount for transactions	Numeric values	Not Applicable
returnTransactionAmountAboveThreshold	Optional	Specifies whether to return transactions above the threshold	Boolean (true/false)	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/AAFIData' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "consentId": "<Enter_the_consent_ID>",
    "sessionId": "<Enter_the_session_ID>",
    "custId": "<Enter_the_phone_number>",
    "transactionAmountThreshold": 0,
    "returnTransactionAmountAboveThreshold": "<true/false>"
}'

Success Response

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

{
  "status": "success",
  "statusCode": "200",
  "metaData": {
    "requestId": "<Unique_Request_ID>"
  },
  "result": {
    "details": {
      "header": {
        "rid": "<Unique_Request_ID>",
        "ts": "<Timestamp_in_ISO_Format>",
        "channelId": "<Channel_ID>"
      },
      "body": {
        "accounts": [
          {
            "linkRefNumber": "<Link_Reference_Number>",
            "status": "<Account_Status>",
            "data": {
              "accountDetails": {
                "accountNumber": "<Account_Number>",
                "accountType": "<Account_Type>",
                "balance": "<Balance>"
              }
            }
          }
        ]
      }
    }
  }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code of the response
requestId	string	A unique identifier for the request
rid	string	A unique identifier for the response
ts	string	The timestamp of the response
channelId	string	The channel through which the request was processed
linkRefNumber	string	A unique reference number for the linked account
status	string	The status of the linked account
accountNumber	string	The account number of the linked account
accountType	string	The type of the linked account
balance	string	The balance of the linked account

Failure and Error Response Details

An error response from the API contains a failure status, with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Description
401	Missing / Invalid credentials	The appId / appKey is missing or incorrect in the request headers.
403	Access Denied	Please contact HyperVerge
500	Template not found: [Template Name]	Incorrect Template Name provided
500	user address is not valid mobile number	Incorrect Mobile Number provided
500	Bad Request. Required values missing	When one of the Mandatory Input fields is missing or the value against it is missing
500	Bad Request	Invalid details in consent description
500	Cannot deserialize value of type java.util.Date from String "202-03-20T12:14:43.727+0000"	Date format is incorrect
500	Error processing request: FI request data range dates not within consent range	FI from and to date is not within the approved date range
500	Consent Id or session ID is invalid	Cannot fetch FIStatus. ConsentId or SessionId not found
500	Invalid consent handle and session id	Account data not found
	Invalid Session Id or link ref no	Account data not found
500	Invalid Consent Handle	Cannot fetch data. ConsentId not found for Consent Handle
500	Fi Req not triggered	Cannot fetch FIStatus. ConsentId or SessionId not found
500	Invalid Token. User does not have permission	Incorrect Token or Expired Token provided
500	Consent Status not active	Incorrect Consent Handle ID provided or user has rejected consent