post https://in.staging.decentro.tech/v2/banking/mobile_to_account
This API allows the platform to fetch the primary account mapped to the end-customer’s mobile number.
Important Note
Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.
Overview
This API allows Decentro’s clients to retrieve the Bank Account Details and the UPI VPA (Virtual Payment Address) associated with a end-user's mobile number.
Flow
Below is the flow for using this API through Decentro:
- The platform creates the request body by passing the authentication header parameters along with the reference_id and mobile_number in the request body.
- Decentro validates the request payload and processes the request if there are no errors with the request payload.
- Please see the response key section for more information on the possible error responses.
- Decentro will respond with the success message, response code, and key if we were able to successfully fetch the account and VPA details
- The relevant response parameters will be passed within the data block
- Decentro will perform a penny drop (INR 1.00) as a part of the validation process.
- If Decentro is not able to find/fetch the required details:
- The API will respond with the relevant failure message, response code, and key
- We will not propagate any values in the data block
API Endpoint
| Environment | Endpoint |
|---|---|
| Staging | https://in.staging.decentro.tech/v2/banking/mobile_to_account |
| Production | https://in.decentro.tech/v2/banking/mobile_to_account |
Request parameters
Below are the request parameters Decentro expects from client.
| Parameter Name | Data Type | Mandatory (Y/N) | Description |
|---|---|---|---|
| Header | NA | NA | Header body section |
| client_id | NA | Y | client_id assigned to the client by Decentro during on boarding. |
| client_secret | NA | Y | client_secret assigned to the client by Decentro during on boarding. |
| module_secret | NA | Y | module_secret assigned to the client by Decentro during on boarding. Please use the secret shared for the Accounts Module. |
| Body | NA | NA | Body object containing payload details |
| reference_id | String | Y | Unique id assigned to each transaction. Special characters are prohibited. |
| mobile_number | String | Y | Mobile number of the end-customer. The input parameter that needs to be validated. |
Response parameter
Below are the response parameters Decentro propagates to client.
| Parameters | Description |
|---|---|
| decentroTxnId | A unique transaction ID from Decentro against the incoming intent request |
| status | Status of the API request |
| responseCode | A unique response code mapped with API request status. |
| message | Status description of the intent request |
| upiVpa | UPI VPA associated with the mobile number. |
| nameAsPerBank | Name of the account holder as per the bank records. |
| accountNumber | Primary Account Number mapped to the mobile number |
| ifsc | Corresponding IFSC code mapped to the account number |
| bankReferenceNumber | Bank Reference Number for the penny drop performed during the account validation process. |
| responseKey | Response key documenting the status of the API hit and various errors as mentioned here |
Response keys
Below are the response keys propagated by Decentro in the responseKey parameter, which cover all the scenarios a platform can encounter.
| Response Key | Response Message |
|---|---|
| success_account_details_retrieved | Account details retrieved successfully |
| error_decentro_error | Internal Server Error. Kindly retry the transaction after sometime. |
| error_invalid_mobile_number | Please provide a valid mobile number |
| error_validation_blocked | The request could not be completed due to a risk exception by NPCI. Kindly retry the transaction after sometime. |
| error_validation_blocked | Transaction not permitted by the beneficiary bank. |
| error_validation_blocked | The request could not be completed due to a risk exception by the beneficiary bank. Kindly retry the transaction after sometime. |
| error_beneficiary_bank_offline | The request could not be completed due to a error with the beneficiary bank. Kindly retry the transaction after sometime. |
| error_validation_blocked | The request could not be completed as it was rejected by the beneficiary bank. |
| error_invalid_vpa_mapped | An invalid VPA is mapped to this mobile number. |
| error_mobile_mapping_not_supported | The PSP for this VPA does not support Mobile Number and UPI VPA linkage. |
| error_validation_failed | Account details could not be fetched due to an issue with the beneficiary bank. Kindly retry the transaction after sometime. |
| error_network_timeout_rejection | The transaction request could not be completed due to high response time from NPCI. Kindly retry the transaction after sometime. |
| error_mapping_blocked | The request was blocked by NPCI. Please try again after some time. |
| error_mapping_inactive | The details could not be retrieved as the record is marked as INACTIVE by NPCI. |
| error_vpa_mapping_changed | The UPI VPA is no longer mapped to this mobile number. |
| error_vpa_not_mapped_to_psp | The UPI VPA is not active with the registered PSP. |
| error_dormant_account | The account associated with this mobile number is Inactive or Dormant. |
| error_provider_error | Unexpected response received from provider. Kindly retry the transaction after sometime. |
| failure_account_frozen | The account associated with this mobile number is blocked or frozen. |
| failure_no_account_mapped_to_vpa | There is no bank account associated with the VPA mapped to this mobile number. |
| failure_no_account_mapped | There is no UPI VPA associated with this mobile number. |
Simulation Data
Below is the test data that can be used by platforms to test out standard scenarios for the Mobile to Account API.
The platform is expected to pass the parameters as-is to get the intended scenario.
Simulation Data
Decentro provides the test data which will simulate various scenarios of the API when a transaction takes place.
Note: This test data is only valid in the Staging environment. Please use valid client id, client secret and module secret. Use Mobile number parameter to check the various test cases of this API.
Important: Please refer to the Simulation Data guide Click here
Steps to use this data:
- In the request body, pass request values as shared below in the table, depending on the scenario to be tested.
- Trigger the API with the scenario chosen in Step 1.
- Based on the values provided in Step 1 for each request parameter, the API response will contain the relevant output.
| Mobile Number | Validation Status | Test Scenario |
|---|---|---|
| 8266657824 | SUCCESS | Account details retrieved successfully |
| 8266617854 | SUCCESS | The account associated with this mobile number is frozen. |
| 8266457854 | SUCCESS | The account associated with this mobile number is a NRE account and cannot be validated. |
| 8266457814 | SUCCESS | The account associated with this mobile number is closed. |
| 8263657854 | FAILURE | There is no account associated with this mobile number. |
| 8266607854 | FAILURE | The account associated with this mobile number is inactive and cannot be validated. |
| 8176157814 | FAILURE | Internal Server Error. Kindly retry the transaction after sometime. |
| 8306457714 | FAILURE | Unexpected response received from provider. |