API Reference Guide

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

Onemoney API Gateway URL

https://api-sandbox.onemoney.in/

Please include this before each API endpoint to make API calls

API Authorisation

As a FIU

Digital Signatures

Digital signature generation and validation is currently switched off on our sandbox, for all API-based exchanges between the FIU and the AA. Enabling this involves the exchange of public key information. The same can be done in production-mode through the Central Registry hosted by Sahamati. If you are interested in more information on this, please write to helpdesk@onemoney.in

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…]

Error Codes and Details

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”
}

ErrorobjectThe error object
timestampstring($date-time)Time of the response received
errorcodestringType 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
ExplanationNext Steps
400Bad 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.
400Bad request headers
This errorcode occurs as a response to the API call made, when request headers are unavailableRefer 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
400Invalid 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.
401Invalid 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
401Invalid 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.
401UnauthenticatedThis 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
403AccessDenied
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
404NoSuchVersion
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
405MethodNotAllowed
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
410OTP_VERIFIED_ALREADYThis 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.
410OTP_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.
411MissingContentLengthThis 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
412PreconditionFailed
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.
415UnsupportedMediaType
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
422INVALID_OTPThis 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.
429LimitExceeded
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
500Internal 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
502BadGatewayThis 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
503SERVICE_UNAVAILABLEThis 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
503ERR_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
504GATEWAY_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
520ERR_UNKNOWNThis 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
400InvalidConsentPurpose
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
400InvalidRequest
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
400InvalidConsentHandleThis 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
400InvalidConsentId
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
400InvalidConsentId
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
400InvalidKey
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
400InvalidDateRangeThis 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
403ConsentExpired
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
403ConsentRevoked
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
403ConsentPausedThis 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
404ExpiredKeyMaterial
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
400InvalidConsentId
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
400InvalidSessionId
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
403DataFetchRequestInProgress
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
404NoDataFoundThis 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
410DataGoneThis 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