post
https://staging.api.decentro.tech/v3/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.
This API endpoint and schema is relevant only when integrating with our Payment Aggregator entity (Decfin).
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, consumer_urn, 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 and response 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) or a paisa drop (INR 0.01) 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 and response key
- We will not propagate any values in the data block
- If the
api_statusis "PENDING", please use the GET Mobile to Account Status (V3) API to retrieve the terminal status of the verification request.
Global Velocity Controls are implemented for this API
We ensure this service is not abused via our Global Velocity Controls. Our default velocity limits, set against each mobile number, are 3 per min / 4 per hour / 5 per day.
These limits are in place at to ensure that the same mobile number, or bank account, does not receive unlimited payouts (via the verification penny drop) from multiple verifications within short time-frame.
API Endpoint
| Environment | Endpoint |
|---|---|
| Staging | https://staging.api.decentro.tech/v3/banking/mobile_to_account |
| Production | https://api.decentro.tech/v3/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. |
| Body | NA | NA | Body object containing payload details |
| reference_id | String | Y | Unique id assigned by the client's platform for each API call. Special characters are prohibited. |
| consumer_urn | String | Y | A unique identifier assigned to client's by Decentro during On-boarding. |
| mobile_number | String | Y | Mobile number of the end-customer. The input parameter that needs to be validated. |
| fetch_branch_details | Boolean | N | This flag can be used to fetch the details of the bank branch associated with the bank account. These details will only be propagated when the system is able to retrieve the account details associated with the mobile number. Possible Values: true, false. |
| is_consent_granted | Boolean | N | This flag will be used to capture the end-customers consent to proceed with the verification. Possible Values: true, false. |
Response parameter
Below are the response parameters Decentro propagates to client.
| Parameters | Description |
|---|---|
| decentro_txn_id | A unique transaction identifier from Decentro against the verification request |
| api_status | Status of the API request. Possible Values: SUCCESS, FAILURE, PENDING. |
| message | Status description of the intent request |
| upi_vpa | UPI VPA associated with the mobile number. |
| name_as_per_bank | Name of the account holder as per the bank records. |
| account_number | Primary Account Number mapped to the mobile number |
| ifsc | Corresponding IFSC code mapped to the account number |
| bank_reference_number | Bank Reference Number for the penny drop performed during the account validation process. |
| payout_status | This parameter will contain the status of the penny drop initiated by the system as a part of the verification process. |
| payout_amount | This parameter will contain the amount (INR 0.01 or 1.00) deposited during the penny drop process. |
| account_type | This parameter will contain the nature of the account being validated. Possible values: SAVINGS, CURRENT, NRO. |
| branch_details | This nested block will be propagated when the fetch_branch_details values is passed as true. Please click here to find the list of parameters which will be propagated in a success scenario. |
| branch_verification_response_key | This key will be propagated within the branchDetailsobject and will specify whether or not the branch details, identified during the verification process, are available in our system. |
| response_key | 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 |
|---|---|
| error_malformed_request | Malformed request detected. |
| error_invalid_credentials | Invalid authentication credentials |
| error_missing_credentials | No API key found in request |
| error_invalid_client_credentials | Authentication failed. Please use valid Client ID and Client Secret. |
| error_empty_client_secret | Client Secret cannot be empty. Hint: client_secret (string) |
| error_unauthorized_module | Authentication failed for accessing the module |
| error_empty_module_secret | Module Secret cannot be empty. Hint: module_secret (string) |
| error_company_disabled | Requests are disabled for the company/account. |
| error_mobile_number_type_not_string | Parameter mobile_number should be a string. Hint: mobile_number (string) |
| error_mobile_number_incorrect_string_length | Parameter mobile_number should be exactly 10 characters long after trimming whitespace. Hint: mobile_number (string) |
| error_mobile_number_invalid_mobile_format | Parameter mobile_number should be 10 digits long and start with one of 9, 8, 7 or 6. |
| error_reference_id_missing_or_null | Parameter reference_id cannot be missing/null. Hint: reference_id (string) |
| error_invalid_reference_id | Reference ID is not of type string |
| error_duplicate_reference_id | Duplicate Request Reference ID |
| error_empty_reference_id | Request reference ID cannot be null or empty. Hint: reference_id (string) |
| error_invalid_reference_id_length | Request reference ID is not valid. Hint: reference_id should be restricted to 2 to 100 chars |
| error_fetch_branch_details_type_not_boolean | Parameter fetch_branch_details should be a boolean. Hint: fetch_branch_details (boolean)" |
| error_is_consent_granted_type_not_boolean | Parameter is_consent_granted should be a boolean. Hint: is_consent_granted (boolean) |
| error_unsanitized_values | Unsanitized values detected for key(s): <key_name>. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry. |
| 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. |
| failure_account_closed | The account associated with this mobile number is closed. |
| error_velocity_controls_verification_failed | Transaction failed due to velocity controls for combination: mobile_number. Limit is hits per . Please try again later. |
| success_branch_details_found | This value will be propagated in the branchVerificationResponseKey parameter when the fetch_branch_details values is passed as true and the system is able to successfully find the required details. |
| error_branch_details_not_found | This value will be propagated in the branchVerificationResponseKey parameter when the fetch_branch_details values is passed as true but the system is unable to find the required details. |