Skip to content

PAN Account Linkage API

New

Check whether a submitted PAN and bank account appear linked in the available information, and settle it before a disbursal, settlement or payout run depends on the answer.

Overview

A PAN account linkage check tells you whether a submitted Permanent Account Number and a submitted bank account appear linked in the available information. Banks hold a PAN against the accounts they open. Any process that pays money out assumes the receiving account belongs to the person whose PAN sits on the file. An API check reads that status inside the workflow that already holds both values. You get the answer while a correction is still cheap, instead of meeting it as a failed credit or a held settlement. Your application submits the PAN and the account details, and a linkage status comes back in a structured response. The question is narrower than account verification. Penny Drop and Penny Less show that an account exists and whose name the bank holds against it. This check reports whether that account and the PAN appear associated. Available fields vary by data source and record, and the scope of a response depends on the selected service contract.

Coverage
Linkage status for a submitted PAN and Indian bank account
Input
A PAN, and the bank account it is checked against (account number and IFSC)
Output
A linkage status for the submitted pair, in a structured response. Available fields vary by data source and record.
Typical users
Lenders and NBFCs, fintech and payment platforms, insurers, marketplaces, staffing and gig platforms, enterprise finance teams
Coverage note
Shows what available information holds for the submitted pair at the time of the check. The selected service contract sets the scope.

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/pan-bank-link

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.panstringRequired—Matches ^[A-Z]{5}[0-9]{4}[A-Z]$. Exactly 10 characters
input.accountNumberstringRequired—Matches ^[0-9]{9,18}$
input.ifscstringRequired—Matches ^[A-Z]{4}0[A-Z0-9]{6}$. Exactly 11 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/pan-bank-link \
  -H "X-Api-Key: $FINSOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "pan": "<pan>",
    "accountNumber": "<accountNumber>",
    "ifsc": "<ifsc>"
  },
  "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/pan-bank-link", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.FINSOUR_API_KEY,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {
      "pan": "<pan>",
      "accountNumber": "<accountNumber>",
      "ifsc": "<ifsc>"
    },
    "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/pan-bank-link",
    headers={
        "X-Api-Key": os.environ["FINSOUR_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "input": {
            "pan": "<pan>",
            "accountNumber": "<accountNumber>",
            "ifsc": "<ifsc>",
        },
        "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.maskedPanstringAlwaysThe PAN sent, as its display form.Matches ^[A-Z]{3}X{5}[0-9][A-Z]$
data.maskedAccountNumberstringAlwaysThe account number sent, as its display form.Matches ^X{5,14}[0-9]{4}$
data.ifscstringAlways—Matches ^[A-Z]{4}0[A-Z0-9]{6}$. Exactly 11 characters
data.linkedboolean or nullAlwaysWhether the bank holds this PAN against this account; null when the account is not found.—
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 and NBFCs: check the disbursal account against the applicant PAN before release
  • Fintech and payments: check a merchant settlement account during onboarding
  • Insurance: check the claimant account before a settlement reported for tax
  • Marketplaces: check a seller account before a payout is released
  • Staffing and gig platforms: check worker accounts ahead of a payout run
  • Enterprise finance: check a vendor account before the first payment is made

What this service does

  • One question: are they linked?

    The check reports whether the submitted PAN and bank account appear linked in the available information. It does not confirm identity, verify either value on its own, or describe the balance or state of the account.

  • How it differs from Penny Drop

    Penny Drop and Penny Less show that an account exists and whose name the bank holds against it. This check reports whether that account and the PAN appear associated, which is the part a payout run assumes and rarely checks.

  • Inconclusive gets its own answer

    A pair the available information holds nothing about comes back as inconclusive, not as a negative. Your workflow can route the two down separate paths, instead of treating a gap in the records as a decision against the customer.

  • Catch a mismatch before the payout

    Run the check while a file is being prepared and a mismatch becomes something the customer can correct. The same mismatch found after the payment is a reversed credit, a support ticket and a re-run.

How a check runs

  1. Tell us what you are building

    Tell us about the workflow you have in mind. We agree the services your contract covers and the onboarding steps for your environment.

  2. Check the consent covers both values

    Confirm that the customer relationship, the consent and the business reason cover a check that relates a PAN to a bank account, before any request is sent.

  3. Send the PAN and the account

    Your application sends the PAN with the bank account details it should be checked against, normally the account number and the IFSC. Both come from the workflow that already holds them.

  4. Read the linkage status

    The available information comes back as a structured status for the submitted pair, with a clear inconclusive outcome where the records hold nothing about it.

  5. Split the three outcomes

    Send a clear status, an inconclusive result and a mismatch down separate paths. Record the status against the file, and tell the customer what to correct where a mismatch is what holds the payment.

Questions

What do I send to check PAN and bank account linkage?
A pair: the PAN, and the bank account it should be checked against, normally the account number with the IFSC. Both come from your own customer file, and both should be covered by the consent and authorization your relationship with that customer rests on.
Is a PAN linkage check the same as Penny Drop or Penny Less?
No. Those answer whether an account exists and can receive a credit, and Penny Drop also returns the name the bank holds against it. This answers whether that account and the submitted PAN appear associated in the available information. Teams paying out at scale usually run both, because the account must be reachable and must belong to the person the file is about.
What does a PAN account linkage response include?
A linkage status for the submitted pair, in a structured response. The fields available may vary with the underlying data source and the record, and the scope of a response depends on the selected service contract.
What does a linked or not linked status actually mean?
It means the PAN and the bank account do, or do not, appear associated in the available information at the time of the check. Read it literally. It is not a confirmation of identity, not a verification of either value on its own, and not a description of the balance or state of the account.
Do I need consent to link a PAN to a bank account?
Yes. Consent and an authorized business purpose are both required, and both values should already sit on a customer file you hold. Keep consent specific and revocable, limit retention to what the purpose needs, and log each check against the file that justified it.
How do I get access to the PAN Account Linkage API?
Use Get API to tell us what you are building. We take coverage, the service contract and the onboarding steps from there.

Catalog entry last updated .