UPI Advanced V2

Endpoint Overview

POST /api/v1/bank-verification/upi-advanced-v2

Description

The UPI Advanced V2 API provides a comprehensive verification solution for Unified Payment Interface (UPI) IDs. It validates the provided UPI ID (also known as Virtual Payment Address or VPA) and retrieves detailed information associated with it, including the account holder's name, bank details, branch information, and address. This API enables businesses to verify payment recipients before initiating transactions, reducing the risk of misdirected payments and enhancing security in digital financial transactions.

Key Benefits

Enhanced Payment Security: Verify UPI IDs before initiating transactions to prevent misdirected payments

Comprehensive Data Retrieval: Access detailed information including bank name, branch, and account holder details in a single API call

Fraud Prevention: Validate payment recipients' identities to reduce fraudulent transaction attempts

Seamless User Experience: Implement real-time verification to improve customer confidence and reduce payment failures

Use Cases

Financial Services

E-commerce

FinTech

Verify recipient UPI IDs before processing high-value transactions

Validate customer-provided UPI details during account linking

Implement real-time verification during payment setup to reduce failed transactions

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
upi_id	String	Yes	UPI ID or Virtual Payment Address (VPA) of the account holder to be verified (e.g., "username@bankcode")

Example Request

{
    "upi_id": "kumar32@axisb"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the verification result data
data.client_id	String	Unique identifier for the verification request
data.upi_id	String	The UPI ID that was verified
data.full_name	String	Full name of the UPI ID holder
data.bank	String	Name of the bank linked to the UPI ID
data.branch	String	Branch name of the bank
data.centre	String	Centre information (if available)
data.district	String	District where the bank branch is located
data.state	String	State where the bank branch is located
data.address	String	Complete address associated with the bank account
data.contact	String	Indicates whether contact information is verified ("TRUE" or "FALSE")
data.city	String	City where the bank branch is located
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the API call was successful
message	String or null	Additional information about the response (null if successful)
message_code	String	Code indicating the status of the response

Example Successful Response

{
    "data": {
        "client_id": "upi_advanced_v2_vxwxNJWocdtUAazbHulz",
        "upi_id": "deepak32@axisb",
        "full_name": "DEEPAK KUMAR",
        "bank": "Kotak Mahindra Bank",
        "branch": "CONNAUGHT PLACE BRANCH",
        "centre": "",
        "district": "DELHI",
        "state": "DELHI",
        "address": "123, Green Park Avenue,Near Metro Station, New Delhi, Delhi - 110016",
        "contact": "TRUE",
        "city": "DELHI"
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid UPI ID

Authentication Error

Server Error

{
    "data": {
        "client_id": "upi_advanced_v2_cNcdcMwyUDhMljozRjkk",
        "upi_id": "7827216sadf",
        "full_name": null,
        "bank": null,
        "branch": null,
        "centre": null,
        "district": null,
        "state": null,
        "address": null,
        "contact": null,
        "city": null
    },
    "status_code": 422,
    "success": false,
    "message": "Invalid UPI ID",
    "message_code": "invalid_upi_id"
}

This error occurs when the provided UPI ID format is incorrect or the UPI ID doesn't exist in the banking system.

Integration Best Practices

Security Recommendations

Store API keys and tokens securely, never expose them in client-side code

Implement proper error handling to prevent sensitive information leakage

Use HTTPS for all API communications to ensure data encryption in transit

Implement rate limiting on your end to prevent abuse of the API

User Experience Guidelines

Implement real-time verification during UPI ID input to provide immediate feedback

Display appropriate error messages that guide users to correct invalid UPI IDs

Show a loading indicator during verification to indicate processing

Cache verified UPI details (securely) to reduce repeated API calls for the same UPI ID

Code Samples

cURL

Python

Node.js

Related APIs

UPI Basic Verification API: Provides basic verification of UPI IDs without detailed information

Bank Account Verification API: Verifies bank account details using account number and IFSC code

PAN Verification API: Verifies Permanent Account Number (PAN) details for KYC purposes

Compliance and Legal Considerations

When implementing UPI verification, be aware of data privacy regulations such as the Personal Data Protection Bill in India. Ensure you have appropriate consent from users before verifying their UPI IDs. The information retrieved should only be used for the specific purpose disclosed to the user, such as payment verification or KYC processes. Store verification data securely and in compliance with applicable data protection laws.

{ "data": { "client_id": "upi_advanced_v2_vxwxNJWocdtUAazbHulz", "upi_id": "deepak32@axisb", "full_name": "DEEPAK KUMAR", "bank": "Kotak Mahindra Bank", "branch": "CONNAUGHT PLACE BRANCH", "centre": "", "district": "DELHI", "state": "DELHI", "address": "123, Green Park Avenue,Near Metro Station, New Delhi, Delhi - 110016", "contact": "TRUE", "city": "DELHI" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

UPI Advanced V2

UPI Advanced V2#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

UPI Advanced V2

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples