UPI Verification

Endpoint Overview

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

Description

This API endpoint allows you to validate the existence of a UPI (Unified Payments Interface) account associated with a given UPI ID. The service performs a real-time verification of the UPI ID and returns detailed information including whether the account exists, the UPI ID itself, the full name of the account holder, and any additional remarks.

This verification is essential for businesses that need to confirm the validity of UPI IDs before processing payments or setting up recurring transactions, helping to reduce failed transactions and improve the overall payment experience.

Key Benefits

Instant verification of UPI IDs to confirm their validity before initiating transactions

Reduction in payment failures due to incorrect or non-existent UPI IDs

Access to account holder's name for additional verification and fraud prevention

Seamless integration into payment flows and user onboarding processes

Use Cases

Financial Services

E-commerce

Subscription Services

Verify customer UPI IDs during account setup to ensure payment methods are valid

Validate UPI IDs before processing high-value transactions to reduce fraud risk

Implement real-time UPI verification during customer onboarding for smoother experiences

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	Bearer token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
upi_id	String	Yes	UPI ID or VPA (Virtual Payment Address) of the account holder to be verified. Format examples: `username@upi`, `mobilenumber@bank`, etc.

Example Request

{
    "upi_id": "1234567890@ybl"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the verification result data
data.client_id	String	Unique identifier of the Client
data.account_exists	Boolean	Indicates whether the UPI account exists (true/false)
data.upi_id	String	The UPI ID that was verified
data.full_name	String	Full name of the UPI account holder
data.imps_ref_no	String	IMPS Reference Number
data.remarks	String	Remarks
data.status	String	Status (from predefined enum values)
data.ifsc_details	Object	IFSC details of the UPI account
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API request was successful
message	String or null	Additional message about the response (if any)
message_code	String	Code indicating the status of the request

Example Successful Response

{
    "data": {
        "client_id": "upi_validation_yowhoilsErgUZldeexzt",
        "account_exists": true,
        "upi_id": "1234567890@ybl",
        "full_name": "Munna Bhaiya",
        "imps_ref_no": "",
        "remarks": "",
        "status": "",
        "ifsc_details": ""
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid UPI ID

Authentication Error

Server Error

{
    "data": {
        "client_id": "upi_validation_cNcdcMwyUDhMljozRjkk",
        "account_exists": false,
        "upi_id": "7827216sadf",
        "full_name": null,
        "imps_ref_no": null,
        "remarks": null,
        "status": null,
        "ifsc_details": null
    },
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

Occurs when UPI ID is invalid or doesn't exist.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to manage failed verifications gracefully

Rotate authentication credentials periodically according to your security policies

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

User Experience Guidelines

Validate UPI ID format on the client-side before making API calls to improve response times

Display a user-friendly loading state during verification to indicate processing

Clearly communicate verification results to users, especially in case of failures

Consider implementing a retry mechanism for temporary verification failures

Code Samples

cURL

Python

Node.js

Related APIs

Bank Account Verification API - Verify bank account details including account number and IFSC code

PAN Verification API - Verify Permanent Account Number details for KYC purposes

Aadhaar Verification API - Verify Aadhaar card details for identity verification

Compliance and Legal Considerations

When implementing UPI verification, ensure you comply with relevant data protection regulations and obtain appropriate consent from users before verifying their UPI IDs. The verification process should be transparent to users, and their data should be handled according to privacy policies. Additionally, be aware that UPI verification may be subject to NPCI (National Payments Corporation of India) guidelines and regulations.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/bank-verification/upi-verification' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "upi_id": "1234567890@ybl" }'

{ "data": { "client_id": "upi_validation_yowhoilsErgUZldeexzt", "account_exists": true, "upi_id": "1234567890@ybl", "full_name": "Munna Bhaiya", "imps_ref_no": "", "remarks": "", "status": "", "ifsc_details": "" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

UPI Verification

UPI Verification#

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 Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples