UPI Verification API
Popular
Check that a UPI VPA is valid and read the name available against it. That confirms a payout destination before the money moves.
Overview
UPI Verification checks whether a Virtual Payment Address is valid and usable, and returns the name available against it. It answers the two questions a business asks before paying over UPI. Does this handle exist, and does the name behind it look like the person you mean to pay? A handle is easy to mistype, and one wrong character can produce an address that still belongs to somebody. Run the check when a beneficiary is added, and again before a payout run, and a misdirected payment becomes a caught error. Available fields vary by data source and by record, and some handles return an abbreviated or bank-formatted name. Verify only handles a customer has given you for a payment purpose.
- Category
- Banking Services
- Coverage
- India; UPI Virtual Payment Addresses, subject to the availability of the underlying record
- Input
- UPI Virtual Payment Address (VPA), captured with consent
- Output
- Validity status for the handle and the name available against it, where the source provides one
- Typical users
- Payout, onboarding, treasury and risk teams across lending, insurance, marketplaces and gig platforms
- Coverage note
- Name formatting and available fields vary by data source and record; some handles return no name
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
input | object | Required | The details to check. | — |
input. | string | Required | — | Matches ^[a-z0-9._-]{2,256}@[a-z][a-z0-9]{1,63}$. At most 255 characters |
options | object | Required | Settings for this call. This API requires consent. | — |
options. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
options. | object | Required | The person's consent to this check. | — |
options. | boolean | Required | Send true once the person has agreed to the check. | Always true |
options. | string (date-time) | Required | When the person gave consent. | — |
options. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/banking/vpa \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"vpa": "<vpa>"
},
"options": {
"consent": {
"obtained": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/banking/vpa", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"input": {
"vpa": "<vpa>"
},
"options": {
"consent": {
"obtained": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}),
});
console.log(response.status, await response.json());Python
import os
import uuid
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/banking/vpa",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"vpa": "<vpa>",
},
"options": {
"consent": {
"obtained": True,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc",
},
},
},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The result of the check. | — |
data. | boolean | Always | — | — |
data. | string | Always | — | Matches ^[a-z0-9._-]{2,256}@[a-z][a-z0-9]{1,63}$. At most 255 characters |
data. | string or null | Always | The name a payment to this VPA would reach. | — |
data. | string or any or null | Always | — | — |
data. | object | Always | — | — |
data. | string | Always | When the answer was fetched: RFC 3339 UTC with a Z, never an epoch or an IST offset. | Matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
CONSENT_REQUIRED | 422 | This product requires an explicit consent flag. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Lending: confirm the disbursement destination before a loan amount is released
- Insurance: verify a claimant's handle before settlement and agent handles before commission runs
- Fintech and payments: show a confirmed payee name on the beneficiary-add screen
- Marketplaces: re-verify seller payout handles whenever settlement details are changed
- Gig, staffing and logistics: validate worker and driver handles before recurring payout cycles
- Travel and healthcare: check refund destinations before a cancellation or billing refund is approved
What this service does
Catch a wrong handle before release
The check runs before funds move. A wrong or edited handle is caught while it is still a correction. A misdirected UPI transfer is harder to unwind than a failed one.
Validity status and the payee name
The response carries validity status for the submitted handle and the name available against it, with whatever status information the underlying source provides. Available fields vary by data source and by record, and some handles return no name.
No money moves: repeat it often
The check does not move money. You can run it at every point where the risk sits. Run it when a beneficiary is added, before a payout run, and again whenever a handle is edited.
Your risk team sets the match threshold
The returned name is compared against the one you already hold. Indian names vary in order, initials and formatting. Your risk team sets the match threshold and decides what a partial match should trigger.
How a check runs
Collect the UPI handle for a payment
Take the UPI handle from the customer, worker or seller for a stated payment purpose, with a notice explaining what the check is for.
Send the handle for verification
Your application sends the handle through the API from the beneficiary-add screen, the onboarding journey or the payout run that needs it.
Read the status and the name
The response carries validity status for the handle and the name available against it, where the underlying source provides one.
Compare it with the name on file
Match the returned name against the KYC record, policy or agreement you already hold, using a threshold your risk team has agreed.
Release, review or ask for a new handle
Release the payout on a clean match, route a partial match to manual review, and ask for a corrected handle where nothing was returned.
Questions
- What is a UPI Verification API?
- An interface that validates a UPI Virtual Payment Address and returns the name available against it. A business can confirm a payout destination inside its own software, instead of checking each handle separately by hand.
- What does a UPI verification response contain?
- Validity status for the submitted handle and the name available against it, together with whatever status information the underlying source provides. Available fields vary by data source and by record, and some handles return no name at all.
- Why does the UPI name not match my records exactly?
- Banks format names differently, and Indian names arrive in different orders, with initials expanded or contracted and with or without a surname. Some records also return an abbreviated or bank-formatted version of the name you hold. Plan for a fuzzy comparison, not an exact string match.
- Does a matching name prove the payee is who they say?
- No. A match confirms the name available against the handle. It is not an identity check, and it does not establish that the person you are dealing with controls that handle. Use it alongside the KYC and risk checks the decision already relies on.
- When should I run a UPI VPA check?
- Commonly at two points: when a beneficiary is first added, and again immediately before funds move, because a handle can be edited between the two.
- What consent does a UPI VPA check need?
- A handle and the name behind it are personal data: verify only handles given to you for a payment purpose, and keep the result inside that purpose. Verification is not a directory lookup. It must never be used to enumerate handles or to confirm names you have no reason to hold.
Catalog entry last updated .