post
https://in.staging.decentro.tech/v3/banking/money_transfer/validate_bank_account
Updated Validate Bank Account with smart provider selection.
Important Note
Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.
API Endpoints
| Environment | Endpoint |
|---|---|
| Staging / Sandbox | https://in.staging.decentro.tech/v3/banking/money_transfer/validate_bank_account |
| Production | https://in.decentro.tech/v3/banking/money_transfer/validate_bank_account |
This API allows you to validate a bank account by doing a penny drop (small deposit)/penniless transaction automatically. This is a sync API and Decentro returns the response of the account immediately.
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.
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. Note: For all the scenarios, use the following consumer_urn = 4ac34260a0e34e4f82069e85b4a881fd.
- 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.
| To Account | IFSC Code | Validation Scenarios | Validation Status |
|---|---|---|---|
| 121416119212 | SBIN0001077 | Validate Bank Account API, Account Status as 'Valid' | Success |
| 12321890150 | DBSS0IN0811 | Validate Bank Account API, Account Status as 'Invalid' | Failure |
API Specifications
Request Payload
| Request Parameter | Mandatory (M) / Optional (O) / Conditional Mandatory (CM) | Description |
|---|---|---|
| reference_id | M | A URN to be passed by the user for each API request. Alphanumeric values are allowed. Special characters such as “@ # $ % ^ & * ! ; : ~ ` ? = + ) ( apostrophe, double quotes” are not allowed |
| purpose_message | M | 1. The narration/remarks that will be displayed in the beneficiaries bank statement. 2. Minimum length is 5 characters and Maximum length is 255 characters. No special characters allowed. |
| consumer_urn | M | A URN created for a consumer must be passed here. |
| perform_name_match | O | To compare the name from the name parameter and beneficiary name. Boolean value is supported. |
| validation_type | M | The validation method to be passed. The accepted values are 1.penniless 2.pennydrop 3.hybrid |
| beneficiary_details | M | Object |
| name | O | The Beneficiary Account Holder's Name must be added. Mandatory if "perform_name_match" is present. Note: No name validation is being performed. |
| account_number | M | Beneficiary Account Number to be added. The account number that needs to be validated. |
| ifsc | M | Beneficiary IFSC code to be added. 1. Alphanumeric values are allowed as per the IFSC code assigned to the beneficiary bank. 2. Maximum length is 11 characters. |
| mobile_number | O | 10 digit mobile number must be passed. |
Response Payload
| Parameter | Mandatory (M) / Optional (O) / Conditional Mandatory (CM) | Description |
|---|---|---|
| decentro_txn_id | M | A unique transaction ID generated by Decentro. |
| api_status | M | The status of the API. These are the status available 1. Success 2. FailureNote that this is not the status of the transaction. |
| response_key | M | Response key documenting the status of the API hit and various errors. |
| message | M | API status message. Note that this is not about the status of the transaction. |
| data | Object | |
| beneficiary_name | CM | The beneficiary name of the account holder. The name will come only when account is valid. |
| account_status | M | The status of the validation of account 1. Valid 2. Invalid 3. Inconclusive 4. NRE 5. Blocked 6. Blacklisted |
| bank_reference_number | CM | The bank reference number of the transaction performed. |
| validation_type | CM | The Validation method performed for this request. This parameter will show the values "Penniless" and "Penny Drop". |
| validation_message | CM | The status message of the validation performed |
| name_match_percentage | CM | The percentage propagated from performing the name match. Note: Name match will take place only if the account is valid. |
Response Keys
Below are the response keys propagated by Decentro in the response_key parameter, which cover all the scenarios a platform can encounter.
| Scenario | Response Key | Response Message |
|---|---|---|
| Missing consumer_urn | error_consumer_urn_missing_or_null | Parameter consumer_urn cannot be missing/null. Hint: consumer_urn (string) |
| Invalid consumer_urn type | error_consumer_urn_type_not_string | Parameter consumer_urn should be a string. Hint: consumer_urn (string) |
| Short consumer_urn | error_consumer_urn_insufficient_string_length | Parameter consumer_urn should be at least 1 characters long after trimming whitespace. Hint: consumer_urn (string) |
| Missing purpose_message | error_purpose_message_missing_or_null | Parameter purpose_message cannot be missing/null. Hint: purpose_message (string) |
| Short purpose_message | error_purpose_message_insufficient_string_length | Parameter purpose_message should be at least 1 characters long after trimming whitespace. Hint: purpose_message (string) |
| Invalid purpose_message type | error_purpose_message_type_not_string | Parameter purpose_message should be a string. Hint: purpose_message (string) |
| Missing validation_type | error_validation_type_missing_or_null | Parameter validation_type cannot be missing/null. Hint: validation_type (string) |
| Short validation_type | error_validation_type_insufficient_string_length | Parameter validation_type should be at least 1 characters long after trimming whitespace. Hint: validation_type (string) |
| Invalid validation_type type | error_validation_type_type_not_string | Parameter validation_type should be a string. Hint: validation_type (string) |
| Invalid name_match type | error_perform_name_match_type_not_boolean | Parameter perform_name_match should be a boolean. Hint: perform_name_match (boolean) |
| Missing beneficiary_details | error_missing_key_beneficiary_details | Parameter beneficiary_details cannot be missing/null. |
| Missing account_number | error_account_number_missing_or_null | Parameter account_number cannot be missing/null. Hint: account_number (string) |
| Invalid account_number type | error_account_number_type_not_string | Parameter account_number should be a string. Hint: account_number (string) |
| Missing IFSC | error_ifsc_missing_or_null | Parameter ifsc cannot be missing/null. Hint: ifsc (string) |
| Invalid IFSC type | error_ifsc_type_not_string | Parameter ifsc should be a string. Hint: ifsc (string) |
| Invalid IFSC length | error_ifsc_incorrect_string_length | Parameter ifsc should be exactly 11 characters long after trimming whitespace. Hint: ifsc (string) |
| Invalid mobile_number format | error_mobile_number_invalid_mobile_format | Parameter mobile_number should be 10 digits long and start with one of 9, 8, 7 or 6. |
| Unsanitized input values | error_unsanitized_values | Unsanitized values detected for key(s): mobile_number. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry. |
| Empty name | error_empty_name | Parameter name cannot be null or empty when perform_name_match is set to True. |
| No active metering plan | error_no_active_metering_plan | No active metering plan found for this company |
| No active plan | error_no_active_plan_found | No active plan configuration found |
| One-time plan error | error_plan_type_one_time | Invalid plan type for this API. Please contact the support team. |
| Missing API pricing configuration | error_no_active_plan_found | API pricing not configured in the plan. Please contact the support team. |
| Insufficient credits | error_insufficient_credits | Insufficient credits for account validation |
| Invalid consumer_urn | error_invalid_consumer_urn | No consumer found for the provided consumer_urn: {consumer_urn} |
| Feature unavailable | error_provider_feature_unavailable | Feature not available for the selected provider. |
| Unprocessable entity | error_unprocessable_entity | All the providers are exhausted for account validation. Please drop a mail to `[email protected]. (Hint: No consumer pg details entry found) |
| Insufficient balance | error_insufficient_balance | Remitter account balance insufficient for the penny drop. Kindly fund the respective account for penny drop. |
| Internal server error | error_internal_server_error | Internal Server Error. Please verify if any debit has occurred before retrying. |