Public Tech Platform for Frictionless Credit

Account Aggregator Service API Specification

Document Version 1.4

May 2024

RESERVE BANK INNOVATION HUB, BANGALORE

Revision History

Revision Revision Date Author API Summary of Changes

Number Version
1.0 19th Jun 2023 RBIH 1.0 Initial Version
1.1 28th Aug 2023 RBIH 1.0 Minor Update
1.1.5 30th Oct 2023 RBIH 1.0 Document format Change
1.2 12th Dec 2023 RBIH 1.2 API Version changed
1.3 21st Mar 2024 RBIH 1.2 Added Response Header
1.4 09th May 2024 RBIH 1.4 For ReBIT 2.0.0 Integration:
Platform AA API 1.4 will call AA service
provider endpoint ver 2.0.0 .
Change in request and response payload
data according to ReBIT FIU 2.0.0,
is mentioned in section 6.1 and 7.1

Customer Support
For technical support, please contact the Platform support centre (PSC).
Support email address [email protected] (for ticket creation)
[email protected] (for email communication with
Support)
We respond within 2 hours during business hours (8 am to 8 pm IST)
Table of Contents
1 INTRODUCTION 4
2 OBJECTIVE OF THIS DOCUMENT 4
3 PREREQUISITES 4
3.1.1 IP WHITELISTING 4
3.1.2 URL WHITELISTING 4
3.1.3 PLATFORM CREDENTIAL GENERATION 5
3.1.4 SERVICE SUBSCRIPTION 5
3.1.5 TOKEN GENERATION 5
4 API ENDPOINT FOR CONSENT 6
4.1 SERVICE URL CONSENT 6
4.1.1 URLS 6
4.1.2 REQUEST TYPE 6
4.1.3 URL PARAMETER 6
5 API HTTP Headers 7
5.1 HTTP HEADERS 7
6 API REQUEST PAYLOAD 8
6.1 CONSENT SERVICE REQUEST 8
7 API RESPONSE 10
7.1 Service response 10
8 ERROR CODES 11
9 Support 12

Account Aggregator API Specification Pg| 3

1 Introduction
The Account Aggregator (AA) serves as an intermediary between a User or a FIU and
Financial Information Providers (such as banks, securities, insurance, pensions and other
account/finance management service providers). Application Programming interfaces
enable AA to manage the lifecycle of consent artifacts through the Consent Flow API.
The Account Aggregator API service allows to get consent of the application and fetches
account details from multiple banks.

2 Objective of this Document

To give an overview of the implementation of the API for technical designers and developers to
refer during system integration.

3 Prerequisites
All the below prerequisites are must before integrating the API with Sandbox and Production

3.1.1 IP Whitelisting

- Lenders IPs should be Whitelisted with platform.

- This must be done separately for Sandbox and Production.
- An email with the IP Addresses through which the environment will be access need
to be shared to [email protected] (for ticket creation) and [email protected]
(for email communication).
- Platform IPs should also be whitelisted. RBIH Team will share the IPs to whitelist
while onboarding.
- Kindly ensure that the IPs are whitelisted at both ends before testing the API.

3.1.2 URL Whitelisting

- Below are the URLs of Platform that need to be whitelisted in Lenders Network.
- The Lenders Callback URL need to be whitelisted with Platform.
- This must be done separately for Sandbox and Production.
- Kindly ensure that the URLs are whitelisted at both ends before testing the API.

Non-Prod: Sandbox and UAT Environment

Environment URL
Authentication API service https://auth.nonprod.rbihub.io/
Dev Portal for API catalog and https://am.nonprod.rbihub.io/devportal

Account Aggregator API Specification Pg| 4

 Subscription
API Execution for services https://extgw.nonprod.rbihub.io/
Identity Server https://identity.nonprod.rbihub.io/carbon

Production Environment

Environment URL
Authentication API service https://auth.api.rbihub.io/
Dev Portal for API catalog and https://am.api.rbihub.io/devportal
Subscription
API Execution for services https://extgw.api.rbihub.io/
Identity Server https://identity.api.rbihub.io/carbon

3.1.3 Platform Credential Generation

- Lender should have received the Platform credentials mail with the following details.
o Public Key
o Client ID
o Client Secret
o User Credentials for Dev portal
o Public Certificates

3.1.4 Service Subscription

- Account Aggregator service should be subscribed in Platform Dev Portal

- This must be done separately for Sandbox and Production.
- Steps to subscribe is available in Latest versions of SOP for Lender Onboarding
document -> Section 10
- The credentials for the Login will be shared to registered Users email.
- Kindly ensure that the Service is subscribed before testing the API.

3.1.5 Token Generation

- JWT token is used for authenticating all Platform APIs.

- To generate JWT Token, you need to have follow the steps mentioned in latest version
of Authentication and Authorization API specification document available in Platform
API Spec folder.
- This must be done separately for Sandbox and Production.
- This token will be valid for 6 hours in Sandbox and in Production.

Account Aggregator API Specification Pg| 5

 - Please ensure you have the latest public key which is shared via email to the user
registered.
- Kindly ensure that the valid token availability before testing the API.

4 API Endpoint for Consent

4.1 Service URL Consent

The Account Aggregator API is exposed as a stateless API service over HTTPS. Usage of open-
standard data format in JSON (JavaScript Object Notation) and widely used protocol such as
HTTPS will allow easy adoption of the API by lenders.
The API service path provided follows a standard convention:

/{service name}/{ver}/{lang}

4.1.1 URLs

Sandbox URL https://extgw.nonprod.rbihub.io/aaconsent/1.4/en

Production URL https://extgw.api.rbihub.io/aaconsent/1.4/en

4.1.2 Request type

Set the HTTP request method as POST.

4.1.3 URL parameter

Refer the description of URL Path Parameters below:

URL Parameter Description Value

service name Unique name of the service “aaconsent”

ver Current version of the API “1.4”
lang Language in which the response is “en”
sought. Default language is English

Account Aggregator API Specification Pg| 6

5 API HTTP Headers
5.1 HTTP Headers

Following headers must be passed in the HTTP request.

Header Description Remarks Example

Parameter
Authorization JSON Web Token (JWT) is Bearer EkN-
created and signed by DOsnsuRjRO6BxXemmJD
authentication server upon m3HbxrbRzXglbN2S4sOko
lender request. pdU4IsDxTI8jO19W_A4K
8ZPJijNLis4EZsHeY559a4
Refer the Authentication DFOd50_OqgHGuERTqYZ
and Authorization API yuhtF39yxJPAjUESwxk2J5
specification. k_4zM3O-
vtd1Ghyo4IbqKKSy6J9mT
niYJPenn5-HIirE
api-key A unique key is provided by Optional, 434950ee34353tty33463399
the platform to the lender reserved for
(for future use) during registration for each future purpose.
API. This key is a 24-
character alphanumeric
string consisting of
lowercase letters only
Content-Type “application/json” advised application/json
in the API documentation
(applies to POST requests)
client-id Id in base 64 encoded Base64 encoded pNRxiviTvgBrf7qMANqB
format given by the Client Id VskDYfEa
Platform to the lender at the
time of registration.
provider Service provider code “121” for Perfios,
“122” for Finvu,
“123” for Saafe (yet to be
onboarded)
“124” for NADL (yet to be
onboarded)
“125” for CAMSFinserv
(yet to be onboarded)

Account Aggregator API Specification Pg| 7

 x-jws-signature *Required Alphanumeric eyJ4NXQiOiJNR1JqTWpS
aVlqVTBNVEpqWVRsaU1
tSmpNMlUxT0RWbU56U
mxOamN4WkRZeFptWXl
NRFUwWWciLCJraWQiOi
JOVFJoT0RkallqazNNR1U
zTldGaU9EYzBaREppTmp
sbE9URmtPVGt6TkRBME
1tSXpNV1l4TkdNd05qazF
aak5pTWpsaU4yTTFOMlp
oTnpOalkyTTJPQV9SUzI1
NiIsImFsZyI6IlJTMjU2In0.
eyJzdWIiOiJyYmloaW50Y
WRtaW4iLCJhdXQiOiJBU
FBMSUNBVElPTiIsImF1Z
CI6ImtVU292U1lwZUludU
tfRUluM0hJTDFfWl9Sa2Ei
LCJuYmYiOjE2OTYzOTg
3NTMsImF6cCI6ImtVU29
2U1lwZUludUtfRUluM0hJ
TDFfWl9Sa2EiLCJzY29w
ZSI6ImRlZmF1bHQiLCJpc
3MiOiJodHRwczpcL1wva
WRlbnRpdHkubm9ucHJvZ
C5yYmlodWI
client_api_key *Required Alphanumeric pNRxiviTvgBrf7qMANqB
VskDYfEasdWFss1e4121d
=
x-env-route Header required to access “/sb” /sb
sandbox environment. Not * only for sandbox
required for production

6 API Request Payload

6.1 Consent Service request

According to the policy, the Platform only accepts request messages in JSON format, which
is also referred to as the payload schema or request body template.
Here is the message template structure:

Account Aggregator API Specification Pg| 8

{
"meta": {
"ver": "Version of the request template",
"ts": "timestamp in ISO-8601 format e.g. 2023-01-03T21:10:23+05:30[Asia/Kolkata]",
"txncode": "unique transaction code provided by the lender" },
"data": “<base64 encoded string of the consent request as per ReBIT FIU 2.0.0 request specification>”,
"hmac": "myukAvGKjpafeykYv8j7XyIZVuTrs8VMwuza8TAEHqI=",
}

Key Description
ts Timestamp in ISO-8601
format (yyyy-MM-
ddTHH:mm:ssZ) indicating
the time of initiation of the
request

txncode Unique transaction code

provided by the lender
ver Version associated with the
Service.
data Base64 encoded string of the consent
request as per ReBIT FIU 2.0.0 request
specification.

* Note : This payload will have

different type of consent
requests including consent
request for GSTN. We don't
examine the specific type of
consent request because we just
pass the information along to
account aggregator.
hmac SHA-256 hash of the value
under the key “data”

Account Aggregator API Specification Pg| 9

7 API Response
7.1 Service response

Following is the API service response from the account aggregator consent API
{
"meta": {
"txncode": "412341231",
"ver": "1.4",
"ts": "2024-05-15T17:15:39+0530"
},
"result": {
"errcode": "E000",
"status": "success",
"info": ""
},
"data": {
"ver": "1.4",
"Customer": {
"id": "customer_identifier@AA_identifier"
},
"ConsentHandle": "594b686c-1fbb-4e3c-8aed-5c801dcd891b",
"timestamp": "2024-05-06T11:39:57.153Z",
"txnid": "4a4adbbe-29ae-11e8-a8d7-0289437bf331"
}
"hmac": "myukAvGKjpafeykYv8j7XyIZVuTrs8VMwuza8TAEHqI=",
"signature":
"MEUCIAeQv+ziy089sx2o1Y5lqyPjWtw72BDcvIPhpPNNFw/6AiEA+NE2V83BtyAd5kfu1m0Oa4yhMyiGagf
Am03e0jz81kU=",
"publickey":
"MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAERGnPiFyAyylyIVGiSeUNOVSSqaFCYUSkFP4o9cXoiPi8yq
54Dmknu/90Q4VQLbGKihaNmk+/AwrPsMNVEC4Cew==",
"sig-algo": "SHA256withECDSA"
}

Account Aggregator API Specification Pg| 10

The following table provides explanation of service response parameters.

Response Description
parameter
x-jws-signature Indicates the time of initiation of the request in ISO-8601 format as
yyyy-MM-ddTHH:mm:ssZ.
txncode Unique transaction code provided by the lender.
ver Indicates the version of the JSON response template that is currently
being used.
errcode It’s used to indicate the error code associated with the API service
response. If the response is 'fail status, a relevant error code will be
returned in this field. However, if the transaction is successful, the value
of error code will be 'E000'.
data The base64 encoded data of the request as per ReBIT FIU 2.0.0
specification.

* Note : This response data will have different type of consent requests
including consent request for GSTN. We don't examine the specific type
of consent request because we just pass the information along to account
aggregator.
signature Digital signature hash of the value located under the key "data".
hmac SHA256 hash of the value located under the key “data”
publickey Public key of the platform for source verification purposes.
sig-algo This indicates the algorithm used for signing (signature) the data. For
example, SHA256withECDSA.

8 Error Codes
Refer Latest Platform Error Code pdf to get the list of error values.

The table provided below outlines a comprehensive inventory of platform-specific error codes
utilized by the account-aggregator-service other than common error codes.

Platform ErrorCode Description

E096 x-jws-signature header is missing
E097 client_api_key header is missing

Account Aggregator API Specification Pg| 11

9 Support
If you are facing any issue, please write to us with the following details.

To: [email protected]

Subject: Account Aggregator API Error

Body:

Platform Service Name: Account Aggregator

Platform Environment: Sandbox/Live
Service Provider code: e.g. 121 for Perfios, 122 for FinVuetc.
Request Payload (Header + Body) sent to platform: __________
Error Code received from the platform: ________
Error Message received from the platform: ____________
Attachment: Screenshot/log of the error
8. Prerequisites Status:
- IP Whitelisting –
- URL Whitelisting –
- Service Subscription –
- Token Generation -

Account Aggregator API Specification Pg| 12