Mobile to UPI

Endpoint Overview

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

Description

This API endpoint allows you to retrieve the UPI (Unified Payments Interface) ID associated with a given mobile number. It provides a simple and efficient way to discover UPI payment addresses linked to mobile numbers, enabling seamless integration of UPI payment options in your applications without requiring users to manually enter their UPI IDs.

Key Benefits

Simplifies payment flows by automatically retrieving UPI IDs from mobile numbers

Reduces user input errors by minimizing manual entry requirements

Enhances user experience with faster checkout processes

Enables verification of UPI ID existence before initiating transactions

Use Cases

Financial Services

E-commerce

Utility Payments

Streamline payment collection by automatically retrieving customer UPI IDs

Verify UPI ID existence before sending payment requests

Pre-fill payment forms with discovered UPI IDs to reduce friction

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 <token>`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	String	Yes	The mobile number for which to find the associated UPI ID

Example Request

{
    "mobile_number": "1234567890"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the result data
data.client_id	String	Unique identifier for the API request
data.mobile_number	String	The mobile number provided in the request
data.upi_id	String	The UPI ID associated with the provided mobile number
status_code	Number	HTTP status code of the response
success	Boolean	Indicates whether the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "find_upi_btYgGDVllvsuKxccKofh",
        "mobile_number": "1234567890",
        "upi_id": "xyz123@ybl"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Authentication Error

Server Error

{
    "errors": {
        "mobile_number": "Mobile Number Mobile should not start with 0 and should be of length 10"
    },
    "message": "Input payload validation failed"
}

The mobile number provided is not in a valid format. Ensure it contains only digits.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

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

Always inform users that you will be retrieving their UPI ID using their mobile number

Provide clear error messages when UPI IDs cannot be found

Allow users to manually enter their UPI ID as a fallback option

Implement proper validation of mobile numbers before making API calls

Code Samples

cURL

Python

Node.js

Related APIs

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

UPI Transaction Status API: Check the status of UPI transactions

Mobile Number Verification API: Verify mobile number ownership through OTP

Compliance and Legal Considerations

When using this API, ensure you comply with data privacy regulations such as GDPR or India's Personal Data Protection Bill. Always obtain proper consent from users before retrieving their UPI IDs using their mobile numbers. The information retrieved should only be used for the specific purpose disclosed to the user at the time of consent collection.

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

{ "data": { "client_id": "find_upi_btYgGDVllvsuKxccKofh", "mobile_number": "1234567890", "upi_id": "xyz123@ybl" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Mobile to UPI

Mobile to UPI#

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

Mobile to UPI

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples