API Reference Guide

Complete Developer Guide to Onemoney APIs 

All Onemoney APIs are completely RESTful. All responses are returned in JSON.

The financial data returned as part of responses to data requests are in encrypted XML format. The data is stored as one of the attributes in the JSON response structure.

Onemoney APIs can be used in one of two modes, Test and Live. Visit our developer portal to receive API keys to try out our APIs.

Click here to understand the various error codes

As a FIU

When you access Onemoney APIs, you are authorized based on an FIU ID (Financial Information User ID) and an API key issued to you by us, using the developer portal.

The API key can be generated by you as part of the Settings > API Keys function.

The API key needs to be placed in the header of each API request, as shown below:

Conversely, all APIs implemented by you, such as Post Consent Notification and Post /FI/Notification, that are called by Onemoney, also need to be authorized by you based on an API key issued by you to us.

While using our APIs in test mode, this API key too can be generated by the developer portal through Settings > API Keys function.

As a FIP

[Coming Soon…]

All successful responses are returned with HTTP Status code 200. In case of failure, Onemoney API returns a JSON error response with the parameters that detail the reason for the failure.

Error Response

The error response contains errorcode and timestamp parameters that help you diagnose and solve the error.

To understand more about error codes, refer to the Error Codes section.

Please find the one sample error response below:

{
  “timestamp”: “2020-06-28T16:48:19.112Z”,
  “errorCode”: “InvalidRequest”
}

Error	object	The error object
timestamp	string($date-time)	Time of the response received
errorcode	string	Type of the error

Error Codes

Onemoney aims to make every data transaction successful for its customers. However, in the financial ecosystem errors might still occur because of intermittent communication and technical issues at multiple hops. Hence, it becomes critical for businesses to identify the status of API response and the reason that caused the error. In short, you can identify the reason why any error occurred. This enables you to minimize or fix errors.

Understanding the Error codes

Onemoney AA uses conventional HTTP response codes to indicate the success or failure of an API request.
In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed because of the information provided (e.g., a required parameter was omitted, a transaction failed, etc.).
• Codes in the 5xx range indicate an error with Onemoney AA servers (these are rare).

Note: Some 4xx errors that could be handled programmatically (e.g., account linking failed etc) are explained along with an error code that briefly reports the error details.

Understanding the Error Response

Let us take an example where error occurred when raising a consent.

Sample error response:

{
  “timestamp”: “2020-06-28T16:48:19.112Z”,
  “errorCode”: “InvalidRequest”
}

By looking at the errorcode of the api response, it can be understood that the response is a failure(some error occured) because of using an invalid request. So, this clearly tells the user to go and enter the required request parameters mentioned against the APIs.

Related Information

For the list of common error codes and a quick resolution, you can refer to Common Error Codes.

For API specific error codes and their quick resolution, refer to the API specific Error Codes section.

Common Error Codes

All the possible values for the errorcode parameter in the error response which are common for all the APIs along with their explanation and the next best action to be taken are shown below.

Https Status Code	Error code	Explanation	Next Steps
400	Bad Request	This errorcode occurs as a response to the API call made when a required parameter is missing or an improper request body is sent in the payload of API.	Refer to the Request body table given for the API to check for any missing parameter and add it in the payload of API for making a valid API call.
400	Bad request headers	This errorcode occurs as a response to the API call made, when request headers are unavailable	Refer to the Request body header table given for the API to check for any missing header parameter and add it in the payload of API for making a valid API call
400	Invalid URI	This errorcode occurs as a response to the API call made when the API call couldn"t parse the specified URI/Endpoint	Check the URI/endpoints given against the API for which the response has occurred and replace it with a valid endpoint.
401	Invalid Session ID	This errorcode occurs as a response to the API call made, if the entered sessionId is expired or is not a valid entry	Use Initialize session API for a valid session
401	Invalid apiKey	This errorcode occurs as a response to the API call made,if the entered apiKey parameter as a header of API is either incorrect or invalid	Use the client_api_key parameter given to you.
401	Unauthenticated	This errorcode occurs as a response to the API call made, when the session is invalid or user not logged in.	FIU has to ask the customer to login or use the initialise session API to get a valid session
403	AccessDenied	This errorcode occurs as a response to the API call made, in case when the Web server forbids the user from accessing the API	To resolve the issue contact us at support@onemoney.in
404	NoSuchVersion	This errorcode occurs as a response to the API call made, when the ver parameter value in the request body is incorrect	To resolve the issue change the version to the latest or contact us at support@onemoney.in
405	MethodNotAllowed	This errorcode occurs as a response to the API call made,when the specified API method used is not allowed against the API used	Refer to the specific API in https://www.onemoney.in/docs/api/ to use the method which is allowed to make the API call
410	OTP_VERIFIED_ALREADY	This errorcode occurs as a response to the API call made, when the otp is already verified.	Verification not required, please proceed to the next step.
410	OTP_FAILED_TOO_MANY_ATTEMPT	This errorcode occurs as a response to the API call made, when the otp requested has already reached the final state(verified,expired, failed after too many attempts)	Try after sometime to request OTP again.
411	MissingContentLength	This errorcode occurs as a response to the API call made, when the header of the request body doesn’t contain content-length	Resolve the issue by adding content-length as a header parameter and assigning value as application-json
412	PreconditionFailed	This errorcode occurs as a response to the API call made, when one of the pre-conditions mentioned for the API is not full-filled.	Refer to https://www.onemoney.in/docs/api/ to check for the validations and pre-conditions if any of the request body parameters of the specific API for which this error has occurred.
415	UnsupportedMediaType	This errorcode occurs as a response to the API call made, when the payload is not a json structure.	Please change the payload to json file
422	INVALID_OTP	This errorcode occurs as a response to the API call made, when the otp is either incorrectly entered or invalid	Resolve the issue by requesting OTP again.
429	LimitExceeded	This errorcode occurs as a response to the API call made, when AA exceeds the API call limit accepted by FIP.	To resolve the issue contact us at support@onemoney.in
500	Internal Error	This errorcode occurs as a response to the API call made, when there is an internal error with Onemoney	To resolve the issue try after sometime or contact us at support@onemoney.in
502	BadGateway	This errorcode occurs as a response to the API call made, when there is no valid response from the Onemoney web server	To resolve the issue try after sometime or contact us at support@onemoney.in
503	SERVICE_UNAVAILABLE	This errorcode occurs as a response to the API call made in two cases, One being error connecting to the sms operator and the other being not being able to connect to FIU/FIP	To resolve the issue try after sometime or contact us at support@onemoney.in
503	ERR_CONNECT_SERVICE	This errorcode occurs as a response to the API call made, when the Onemoney server is not able to connect to SQS	To resolve the issue try after sometime or contact us at support@onemoney.in
504	GATEWAY_TIMEOUT	This errorcode occurs as a response to the API call made, when there is no response from the Onemoney server on time	To resolve the issue try after sometime or contact us at support@onemoney.in
520	ERR_UNKNOWN	This errorcode occurs as a response to the API call made, due to a variety of unexpected reasons.	To resolve the issue try it after sometime or contact us at support@onemoney.in

The above error codes are common errors which you might come across all of the APIs and in case the error occurred is specific to API, please refer to API specific Error Codes.

In case you didn’t find a resolution with the above APIs, please reach out to us at helpdesk@onemoney.in

API Specific Error Codes

API Name	HttpStatusCode	Error Title	Explanation	Next Steps
Place a consent Request API	400	InvalidConsentPurpose	This errorcode occurs as a response to the API call made, for the case when the purpose parameter array has an invalid or incorrect value.	Refer purpose table to add correct value of purpose array parameter.
Place a consent Request API	400	InvalidRequest	This errorcode occurs as a response to the API call made, when one or more parameters are missing in the request body of the API.	Refer to the Request body table given for the API to check for any missing parameter and add it in the payload of API for making a valid API call.
Get Status of consent request API	400	InvalidConsentHandle	This errorcode occurs as a response to the API call made, when consenthandle parameter in the request body of the API is either incorrectly entered or invalid	Use Place a consent Request API to get a valid consenthandle parameter as a response.
Fetch the consent artefact	400	InvalidConsentId	This errorcode occurs as a response to the API call made, when the consentId parameter in the request body of the API is either incorrectly entered or invalid	Use Get Status of Consent Request to get a valid consentId as a response parameter.
Place a Data request API	400	InvalidConsentId	This errorcode occurs as a response to the API call made, when the consentId parameter in the request body of the API is either incorrectly entered or invalid	Use Get Status of Consent Request to get a valid consentId as a response parameter.
Place a Data request API	400	InvalidKey	This errorcode occurs as a response to the API call made, when one of the many parameters under keymaterials array is either incorrectly entered or invalid	Use click here option available in the instructions of Request Data API to generate and enter valid parameters under keymaterials array in Place a Data Request API
Place a Data request API	400	InvalidDateRange	This errorcode occurs as a response to the API call made, when the FIDataRange array mentioned in the consent details doesn’t match in Request Consent API.	Use Fetch the Consent Artefact API against the consent raised to get a valid Date range from the array parameters of FIDataRange
Place a Data request API	403	ConsentExpired	This errorcode occurs as a response to the API call made, when the consent raised has expired	Consent has to be raised again to request data, so use Place a consent Request API and Get Status of Consent Request to create and approve consent and use the parameters from Fetch the Consent Artefact API to make a valid Request Data API call.
Place a Data request API	403	ConsentRevoked	This errorcode occurs as a response to the API call made, when the consent is revoked during FI request operation.	FIU has to check with his customer and if revoked, has to place a new consent request using
Place a Data request API	403	ConsentPaused	This errorcode occurs as a response to the API call made, when the consent is paused for now.	FIU has to notify the user about the error, if required request the user to resume.
Place a Data request API	404	ExpiredKeyMaterial	This errorcode occurs as a response to the API call made, when the DHpublic key parameter in Request data API has expired.	Set theDHpublic key parameter in the request body of the API to a latest expiry date.
Fetch Data API	400	InvalidConsentId	This errorcode occurs as a response to the API call made, when the consentId parameter sent in the request body is either incorrectly or invalid	Use Get Status of Consent Request to get a valid consentId as a response parameter.
Fetch Data API	400	InvalidSessionId	This errorcode occurs as a response to the API call made, when the SessionId parameter sent as a request is either incorrectly or invalid	Use Request Data API to get a valid SessionId as a response parameter.
Fetch Data API	403	DataFetchRequestInProgress	This errorcode occurs as a response to the API call made, when FI Data fetch request is already in operation and another FI data fetch request API call is made for the same consentId	FIU has to wait for Onemoney to call the post FIU notification (data readiness notifications) and make the API call after.
Fetch Data API	404	NoDataFound	This errorcode occurs as a response to the API call made, when there is no data found for the requested data using Request Data API	Use the test data created to get data.
Fetch Data API	410	DataGone	This errorcode occurs as a response to the API call made, when the data is purged from the server(occurs only when FIU fetches the data	FIU has to check in their server for data, if not found has to raise a new consent using Place a consent Request API , use Get Status of Consent Request and Place a Data Request API to get data