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.
- Category
- Banking Services
- 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
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-Z]{5}[0-9]{4}[A-Z]$. Exactly 10 characters |
input. | string | Required | — | Matches ^[0-9]{9,18}$ |
input. | string | Required | — | Matches ^[A-Z]{4}0[A-Z0-9]{6}$. Exactly 11 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/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
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The result of the check. | — |
data. | boolean | Always | — | — |
data. | string | Always | The PAN sent, as its display form. | Matches ^[A-Z]{3}X{5}[0-9][A-Z]$ |
data. | string | Always | The account number sent, as its display form. | Matches ^X{5,14}[0-9]{4}$ |
data. | string | Always | — | Matches ^[A-Z]{4}0[A-Z0-9]{6}$. Exactly 11 characters |
data. | boolean or null | Always | Whether the bank holds this PAN against this account; null when the account is not found. | — |
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 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
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.
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.
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.
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.
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 .