Fetch IFSC from UPI ID API

The following document highlights the details of the Fetch IFSC from UPI ID API.

API Description

Objective

The Fetch IFSC from UPI ID API retrieves a user's bank account details such as their Indian Financial System Code (IFSC) from their Unified Payments Interface (UPI) ID, also known as the Virtual Payment Address (VPA).

Input	Output
The user's VPA and name associated with the bank account	The user's IFSC code, the name associated with the bank account, VPA details, and IFSC details

API URL

https://ind-engine.thomas.hyperverge.co/v1/fetchUpiIfsc

API Endpoint

fetchUpiIfsc

Overview

The Fetch IFSC from UPI ID API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should send the request body as JSON through a POST request.

Method - `POST`

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Fetch IFSC from UPI ID API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the Fetch IFSC from UPI ID API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
`vpa`	Mandatory	string	The Virtual Payment Address, also known as the UPI ID of the user	Valid VPA/UPI ID format (e.g., user@paytm)	Not Applicable
`name`	Mandatory	string	The name associated with the bank account corresponding to the provided VPA	Account holder name string	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Fetch IFSC from UPI ID API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/fetchUpiIfsc' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "vpa": "<Enter_the_VPA>",
    "name": "<Enter_the_name>"
}'

Success Response

The following code snippet demonstrates a success response from the Fetch IFSC from UPI ID API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "referenceId": "<Reference_ID>",
        "status": "<Status_of_Vpa>",
        "message": "<Vpa_Verification_Message>",
        "ifsc": "<IFSC_Code>",
        "vpa": "<Virtual_Payment_Address>",
        "nameAtBank": "<Name_At_Bank>",
        "ifscDetails": {
            "bank": "<Bank_Name>",
            "neft": "<NEFT_Status>",
            "imps": "<IMPS_Status>",
            "rtgs": "<RTGS_Status>",
            "upi": "<UPI_Status>",
            "address": "<Bank_Address>",
            "city": "<City>",
            "state": "<State>",
            "branch": "<Branch_Name>",
            "category": "<Bank_Category>",
            "swiftCode": "<SWIFT_Code>",
            "micr": "<MICR_Code>",
            "nbin": "<NBIN_Code>"
        }
    },
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the Fetch IFSC from UPI ID API:

Parameter	Type	Description
`status`	string	The status of the request
`statusCode`	string	The HTTP status code for the response
`result`	object	The JSON object containing the IFSC and VPA verification details
`result.referenceId`	string	A unique identifier assigned to the verification process or transaction
`result.status`	string	The status of the VPA verification, indicating whether it was successful or not
`result.message`	string	A message related to the verification process or transaction
`result.ifsc`	string	The IFSC associated with the bank account. It uniquely identifies a bank branch participating in various payment systems within India
`result.vpa`	string	The VPA provided as input
`result.nameAtBank`	string	The name associated with the bank account corresponding to the provided VPA
`result.ifscDetails`	object	The details related to the IFSC code, including the bank's name, services availability, and location
`result.ifscDetails.bank`	string	The name of the bank associated with the provided IFSC code
`result.ifscDetails.neft`	string	The availability status of the National Electronic Funds Transfer (NEFT) service for the bank
`result.ifscDetails.imps`	string	The availability status of the Immediate Payment Service (IMPS) service for the bank
`result.ifscDetails.rtgs`	string	The availability status of the Real-Time Gross Settlement (RTGS) service for the bank
`result.ifscDetails.upi`	string	The availability status of the Unified Payments Interface (UPI) service for the bank
`result.ifscDetails.address`	string	The full address of the bank branch associated with the IFSC code
`result.ifscDetails.city`	string	The city where the bank branch is located
`result.ifscDetails.state`	string	The state where the bank branch is located
`result.ifscDetails.branch`	string	The name of the bank branch associated with the IFSC code
`result.ifscDetails.category`	string	The category of the bank branch, if applicable
`result.ifscDetails.swiftCode`	string	The SWIFT code for international transactions, if available
`result.ifscDetails.micr`	string	The Magnetic Ink Character Recognition (MICR) code of the bank branch
`result.ifscDetails.nbin`	string	The National Bank Identification Number (NBIN), if applicable
`metaData`	object	The JSON object containing request metadata
`metaData.requestId`	string	A unique identifier for the request

Failure Response

The following code snippet demonstrates a failure response from the Fetch IFSC from UPI ID API when the VPA is invalid:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "referenceId": "<Reference_ID>",
        "status": "INVALID",
        "message": "Vpa entered is invalid.",
        "ifsc": null,
        "vpa": "<User_VPA>",
        "nameAtBank": null,
        "ifscDetails": {
            "bank": null,
            "neft": null,
            "imps": null,
            "rtgs": null,
            "upi": null,
            "address": null,
            "city": null,
            "state": null,
            "branch": null,
            "category": null,
            "swiftCode": null,
            "micr": null,
            "nbin": null
        }
    },
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

Error Responses

The following are some error responses from the Fetch IFSC from UPI ID API:

Invalid VPA
Missing VPA
Missing/Invalid Credentials
Internal Server Error

{
    "message": "vpa should be valid",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

{
    "message": "vpa is missing in the request.",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure" 
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	vpa is missing in the request	The VPA parameter has not been entered in the request	Ensure the request includes the `vpa` parameter with a valid VPA/UPI ID
400	vpa should be valid	The entered VPA is invalid or incorrect	Verify and provide a valid VPA/UPI ID in the correct format (e.g., user@paytm)
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values	Verify and provide valid `appId` and `appKey` credentials
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Method - POST​

Authentication​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Responses​

Error Response Details​