Skip to content

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.

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

POSThttps://gateway.staging.finsour.io/v1/banking/vpa

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

Scheme API key travels in the X-Api-Key header

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

Content type application/json

Headers

NameTypeRequiredDescriptionConstraints
Idempotency-KeystringRequiredA 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

NameTypeRequiredDescriptionConstraints
inputobjectRequiredThe details to check.—
input.vpastringRequired—Matches ^[a-z0-9._-]{2,256}@[a-z][a-z0-9]{1,63}$. At most 255 characters
optionsobjectRequiredSettings for this call. This API requires consent.—
options.referencestringOptionalYour own reference for this call. It comes back unchanged as meta.reference.1 to 128 characters
options.consentobjectRequiredThe person's consent to this check.—
options.consent.obtainedbooleanRequiredSend true once the person has agreed to the check.Always true
options.consent.atstring (date-time)RequiredWhen the person gave consent.—
options.consent.purposestringRequiredWhat 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

Status 200 · content type application/json

NameTypePresentDescriptionConstraints
dataobjectAlwaysThe result of the check.—
data.foundbooleanAlways——
data.vpastringAlways—Matches ^[a-z0-9._-]{2,256}@[a-z][a-z0-9]{1,63}$. At most 255 characters
data.nameAtBankstring or nullAlwaysThe name a payment to this VPA would reach.—
data.statusstring or any or nullAlways——
data.sourceobjectAlways——
data.source.fetchedAtstringAlwaysWhen 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

CodeStatusMeaningRetrying
API_VERSION_UNSUPPORTED400That API version is no longer supported.Do not retry automatically
IDEMPOTENCY_KEY_INVALID400That Idempotency-Key does not meet the required format.Do not retry automatically
IDEMPOTENCY_KEY_REQUIRED400An Idempotency-Key header is required for this request.Do not retry automatically
REQUEST_MALFORMED400The request could not be parsed.Do not retry automatically
AUTH_KEY_EXPIRED401The API key is not valid.Do not retry automatically
AUTH_KEY_INVALID401The API key is not valid.Do not retry automatically
AUTH_KEY_MISSING401No API key was presented.Do not retry automatically
AUTH_KEY_REVOKED401The API key is not valid.Do not retry automatically
INSUFFICIENT_BALANCE402The available balance is not enough for this request.Do not retry automatically
AUTH_IP_NOT_ALLOWED403This API key may not be used from this address.Do not retry automatically
ENTITLEMENT_MISSING403This organization is not entitled to that product in this environment.Do not retry automatically
ORGANIZATION_SUSPENDED403This organization is not active.Do not retry automatically
PRODUCT_NOT_AVAILABLE403That product is not available.Do not retry automatically
PRODUCT_RETIRED403That product has been withdrawn.Do not retry automatically
SCOPE_INSUFFICIENT403This API key does not carry the scope this product requires.Do not retry automatically
PRODUCT_NOT_FOUND404No such product.Do not retry automatically
IDEMPOTENCY_KEY_REUSED409That idempotency key was already used for a different request.Do not retry automatically
PRICE_UNAVAILABLE409No active price covers this product right now.Safe to retry
REQUEST_IN_PROGRESS409An earlier attempt with this key is still running.Safe to retry
SETTLEMENT_PENDING409This request is awaiting reconciliation by an operator.Do not retry automatically
API_VERSION_SUNSET410That API version passed its announced sunset date.Do not retry automatically
REQUEST_TOO_LARGE413The request body is too large.Do not retry automatically
UNSUPPORTED_MEDIA_TYPE415That content type is not accepted on this route.Do not retry automatically
CONSENT_REQUIRED422This product requires an explicit consent flag.Do not retry automatically
SANDBOX_FIXTURE_MISSING422No sandbox fixture exists for this input. Use a different test value.Do not retry automatically
UPSTREAM_REJECTED422The upstream source rejected the input.Do not retry automatically
VALIDATION_FAILED422The request payload is invalid.Do not retry automatically
CONCURRENCY_LIMIT429Too many simultaneous requests.Safe to retry
QUOTA_EXCEEDED429The allowance for this window is spent.Do not retry automatically
RATE_LIMITED429Too many requests.Safe to retry
INTERNAL_ERROR500An unexpected error occurred.Safe to retry
OUTCOME_UNCERTAIN502The outcome of this request is not yet known. Retry with the same Idempotency-Key.Do not retry automatically
UPSTREAM_UNAVAILABLE502The upstream source is unavailable. Retry shortly.Safe to retry
MAINTENANCE_MODE503The service is in a maintenance window.Safe to retry
NO_PROVIDER_AVAILABLE503No provider can serve this product right now.Safe to retry
SERVICE_OVERLOADED503The service is shedding load. Retry shortly.Safe to retry
UPSTREAM_TIMEOUT504The 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

ScopeLimitWindowAt the limit
Your API key, within your organisation's limitThe figure in X-RateLimit-LimitPer minute429 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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 .