Validate a UPI VPA via a penny drop
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 check the status of a UPI VPA (Virtual Payment Address) and, if valid, retrieve the Bank Account Details associated with the VPA.
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 required/mandatory request parameters.
- 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 status
- 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 Status - Verification Request(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 Endpoints
| Environment | Endpoint |
|---|---|
| Staging / Sandbox | https://staging.api.decentro.tech/v3/banking/verify_pay |
| Production | To be confirmed |
This API enabled you yo check if a particular UPI-ID (Virtual Payment Address) is valid.
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 and client_secret values.
- Pass the UPI_VPA values, shared below, in the request payload to cycle through the various test cases for this API.
Important: Please refer to the Simulation Data guide Click here
Please Note: This service is currently not available on for production use.
Simulation Data
Steps to use this data:
- Take the UPI ID from values shared below depending on the scenario to be tested.
- API response will state the validation status of the VPA (valid or invalid)
| UPI ID | API Status | Validation status | Test case |
|---|---|---|---|
| 8972241839@upi | SUCCESS | VALID | When the target UPI VPA is valid |
| 8949342808@upi | SUCCESS | INVALID | When the target UPI VPA is invalid |
| 8949392608@upi | PENDING | Not Applicable | When the sync API responds with a PENDING status |
| 8949342608@upi | FAILURE | Not Applicable | When the request fails due to downstream provider issues |
Response Keys
Below are the response keys propagated by Decentro in the response_key parameter, which cover all the scenarios a platform can encounter.
Please Note: This list is subject to change before this service os deployed on production
| Response Key | Message |
|---|---|
| success_account_details_retrieved | Account details retrieved successfully |
| failure_expired_upi_vpa | The UPI VPA has expired. |
| failure_vpa_restrictred | The customer has blocked trannsactions for this UPI ID. |
| failure_account_frozen | The account associated with this mobile number is blocked or frozen. |
| failure_dormant_account | The account associated with this mobile number is Inactive or Dormant. |
| failure_account_closed | The bank account mapped to the UPI VPA is closed. |
| failure_no_account_mapped | There is no bank account mapped with this UPI ID. |
| faiure_invalid_upi_vpa | The beneficiary UPI VPA is invalid. |
| failure_invalid_vpa | The beneficiary UPI VPA is invalid. |
| failure_invalid_psp | The PSP powering the upi VPA is not active. |
| error_invalid_method | The method is not allowed for the requested URL. |
| (Not Applicable) | Authentication failed. Please use valid Client ID and Client Secret. |
| error_malformed_request | Malformed request detected. |
| error_unauthorized_module | Authentication failed for accessing the module |
| error_unsanitized_values | Unsanitized values detected for key(s): reference_id. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry. |
| error_empty_reference_id | Request reference ID cannot be null or empty. Hint: reference_id (string) |
| error_duplicate_reference_id | Duplicate Request Reference ID |
| error_invalid_reference_id_length | Request reference ID is not valid. Hint: reference_id should be restricted to 2 to 100 chars |
| error_upi_vpa_insufficient_string_length | Parameter upi_vpa should be at least 4 characters long after trimming whitespace. Hint: upi_vpa (string) |
| error_upi_vpa_missing_or_null | Parameter upi_vpa cannot be missing/null. Hint: upi_vpa (string) |
| error_decentro_error | Internal Server Error. 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 remitter bank. Kindly retry the transaction after sometime. |
| error_validation_blocked | Transaction not permitted for this account type (OD/CC/PPI) |
| error_validation_blocked | The customer has not set the MPIN, configured it incorrectly, or has a temporary block as they have exceeded the number of retries. 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 remitting bank. |
| error_validation_blocked | The request could not be completed as it was rejected by the beneficiary bank. |
| error_frequency_limit_breached | The tranasction could not be completed due to a breach of transaction frequency limits set by the custoemr or their 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_techinical_failure | The transaction failed due to a technical failure at NPCI. Kindly retry the transaction after sometime. |
| error_beneficiary_bank_not_supported | The request could not be completed due to the beneficiary bank has not enabled this transaction type |
| error_provider_error | Unexpected response received from provider. Kindly retry the transaction after sometime. |