PAN वेरिफिकेशन API कैसे करें: भारत में डेवलपर के लिए पूरी गाइड

मुख्य बातें

• Endpoint है POST /v1/verify/pan, जिसके लिए API key पर verification.pan.read scope चाहिए। pan ज़रूरी है, name वैकल्पिक (अधिकतम 256 अक्षर)।
• PAN का format ABCDE1234F है: पाँच अक्षर, चार अंक, एक अक्षर। गलत format पर API सीधे 400 लौटाती है, इसलिए यही जाँच अपने फॉर्म में भी लगाइए।
• Response में valid, registeredName, panStatus, nameMatchResult, nameMatchScore, aadhaarSeedingStatus और referenceId जैसे fields आते हैं।
• "PAN असली है" और "यह इंसान वही है" दो अलग बातें हैं। PAN API पहली बात बताती है, दूसरी के लिए आपको अलग तरीका चाहिए।
• valid: false वाला नतीजा भी पूरा किया गया, गिना जाने वाला (billable) verification है, और उसमें भी referenceId आता है।
• API key कभी browser या मोबाइल ऐप में न रखें। call हमेशा आपके सर्वर से जाए।
• Sandbox (sk_test_) मुफ़्त है और आपके wallet से पैसे नहीं काटता। Production (sk_live_) के लिए KYC-approved organization चाहिए।
• PAN संवेदनशील पहचान-डेटा है। सहमति लीजिए, सिर्फ़ ज़रूरी field रखिए और लॉग में पूरा PAN मत छापिए।

ऑनबोर्डिंग फॉर्म में PAN की गड़बड़ी: असली समस्या क्या है?

सहज क्रेडिट नाम के एक काल्पनिक ऐप को लीजिए। यूज़र फॉर्म में PAN डालता है, ऐप उसे database में सेव कर लेता है और अगले दिन ऑपरेशंस टीम हाथ से उसे जाँचती है। जब रोज़ पचास-सौ आवेदन आते हैं तो यह चल जाता है। जब हज़ार आते हैं तो टीम पिछड़ने लगती है और गड़बड़ियाँ पकड़ने में देर होती है।

फॉर्म में PAN की गलतियाँ आम तौर पर चार तरह की होती हैं। पहली, टाइपिंग की चूक: अक्षर और अंक आपस में बदल जाना, जैसे अंकों वाली जगह "O" या "I" लिख देना। दूसरी, format ही गलत होना: नौ या ग्यारह अक्षर, बीच में space, या छोटे अक्षर। तीसरी, ऐसा PAN जो format में सही दिखता है पर रिकॉर्ड में है ही नहीं। चौथी, ऐसा PAN जो रिकॉर्ड में है पर किसी और के नाम पर है, यानी यूज़र ने किसी रिश्तेदार या दोस्त का नंबर डाल दिया।

पहली दो गलतियाँ आप बिना API के, सिर्फ़ फॉर्म की validation से पकड़ सकते हैं और पकड़नी भी चाहिए, क्योंकि हर बेकार call पर आपका समय और बाद में पैसा लगता है। तीसरी और चौथी गलती के लिए रिकॉर्ड से मिलान चाहिए, और यहीं PAN verification API काम आती है।

इसलिए सही तरीका दो परतों का है। पहली परत आपका फॉर्म है, जो format जाँचता है और यूज़र को तुरंत बताता है कि कहाँ चूक हुई। दूसरी परत सर्वर पर होने वाली API call है, जो valid और नाम के मिलान से तय करती है कि आवेदन आगे बढ़े, रुके या किसी इंसान के पास जाए। इस गाइड का बाकी हिस्सा इन्हीं दो परतों को बनाने के बारे में है।

एक और बात: verification का नतीजा सिर्फ़ "पास या फेल" नहीं होता। असली फैसला अक्सर तीन में से एक होता है: आगे बढ़ाओ, रोक लो और यूज़र से दोबारा पूछो, या मैन्युअल रिव्यू में भेजो। आगे के सेक्शन में हम इसी तीन-रास्ते वाले फैसले की बात करेंगे।

PAN वेरिफिकेशन API क्या साबित करती है और क्या नहीं?

इस सवाल का साफ़ जवाब आपके product design को तय करता है, इसलिए इसे ध्यान से पढ़िए।

API क्या बताती है

आप pan भेजते हैं तो जवाब में valid आता है, यानी यह नंबर verification में मान्य पाया गया या नहीं। साथ में PAN की स्थिति (panStatus, panStatusCode, panStatusDescription), रजिस्टर्ड नाम (registeredName), पिता का नाम (fatherName), PAN का प्रकार (type, जैसे Individual) और आधार से जुड़ाव की स्थिति (aadhaarSeedingStatus) भी मिलती है। अगर आपने name भी भेजा था तो nameMatchResult और nameMatchScore बताते हैं कि आपका दिया नाम रिकॉर्ड के नाम से कितना मिलता है।

API क्या नहीं बताती

पहली बात: यह साबित नहीं करती कि फॉर्म भरने वाला व्यक्ति उस PAN का असली मालिक है। अगर किसी को किसी का PAN और नाम पता है, तो वह दोनों सही-सही डाल सकता है और API दोनों को "मिलान" बताएगी। यानी PAN verification एक दस्तावेज़ी जाँच है, व्यक्ति की पहचान की जाँच नहीं। जहाँ पहचान पक्की करना ज़रूरी हो, वहाँ आपको अलग उपाय जोड़ने होंगे, जैसे OTP, लाइव सेल्फी या बैंक खाते का मिलान। यह तय करना आपके जोखिम और आपके नियामकीय दायित्वों पर निर्भर है, इसलिए इसके लिए अपने कानूनी या कंप्लायंस सलाहकार से बात कीजिए।

दूसरी बात: यह आय, टैक्स भरने की स्थिति या क्रेडिट योग्यता के बारे में कुछ नहीं बताती। panStatus PAN की अपनी स्थिति है, व्यक्ति की वित्तीय सेहत नहीं।

तीसरी बात: lastUpdatedAt जैसा field बताता है कि रिकॉर्ड कब का है। इसे "आज की ताज़ा स्थिति" मान लेना ठीक नहीं। अगर आपका काम समय-संवेदनशील है तो इस तारीख को अपने नियम में शामिल कीजिए।

चौथी बात: StampMitra एक निजी LegalTech प्लेटफ़ॉर्म है, जिसे Bani Global Industries LLP चलाती है। यह कोई सरकारी एजेंसी नहीं है और इस गाइड का कोई हिस्सा कानूनी सलाह नहीं है। अपने उपयोग के लिए कौन-सी जाँच काफ़ी है, यह आपके सेक्टर के नियमों पर निर्भर करता है।

इस सीमा को अपने UI के शब्दों में भी दिखाइए। "आपका PAN सत्यापित हुआ" ठीक है, पर "आपकी पहचान सत्यापित हुई" कहना गलत भरोसा पैदा करता है।

पहले अपने फॉर्म में PAN का format कैसे जाँचें?

API की reference में pan का format ABCDE1234F बताया गया है: शुरू के पाँच अक्षर, फिर चार अंक, फिर एक अक्षर। गलत format पर API request को verification के लिए आगे भेजती ही नहीं, सीधे 400 लौटा देती है। इसका उदाहरण संदेश है: pan must match the format ABCDE1234F। यही जाँच आप अपने फॉर्म में पहले कर लें तो यूज़र को तुरंत जवाब मिलता है और आपकी call बचती है।

सफ़ाई पहले, जाँच बाद में

यूज़र जो डालता है उसे पहले साफ़ कीजिए: दोनों तरफ़ के खाली स्थान हटाइए, बीच के space हटाइए और सब अक्षर बड़े (uppercase) कर दीजिए। फिर नीचे वाला pattern लगाइए।

// PAN: 5 अक्षर + 4 अंक + 1 अक्षर
const PAN_REGEX = /^[A-Z]{5}[0-9]{4}[A-Z]$/;

function cleanPan(raw) {
  return String(raw ?? "").replace(/\s+/g, "").toUpperCase();
}

function isPanFormatOk(raw) {
  return PAN_REGEX.test(cleanPan(raw));
}

console.log(isPanFormatOk(" abcde1234f ")); // true
console.log(isPanFormatOk("ABCDE1234"));    // false (9 अक्षर)
console.log(isPanFormatOk("ABCDE12O4F"));   // false (अंक की जगह O)

यह pattern सिर्फ़ ढाँचा जाँचता है। कोई नंबर इस ढाँचे में सही होकर भी रिकॉर्ड में न हो, ऐसा हो सकता है, और वही पकड़ने का काम API करती है।

validation के नियम, एक नज़र में

एक ज़रूरी आदत: क्लाइंट की जाँच पर भरोसा मत कीजिए। कोई भी आपके फॉर्म को छोड़कर सीधे आपके सर्वर पर request भेज सकता है, इसलिए वही जाँच सर्वर पर भी दोहराइए। और अगर API से 400 लौटे तो उसे यूज़र को "PAN का format सही नहीं है, कृपया दोबारा जाँचें" जैसे सरल शब्दों में दिखाइए, कच्चा error संदेश नहीं।

request कैसी दिखती है: endpoint, headers और body

असली request का आकार यह है। Base URL https://api-b2b.stampmitra.in है और path /v1/verify/pan, method POST।

headers

हर request में API key चाहिए। आप इसे Authorization: Bearer <key> में भेज सकते हैं, या x-api-key: <key> header में, दोनों स्वीकार हैं। साथ में Content-Type: application/json रखिए। Sandbox की key sk_test_ से शुरू होती है और production की sk_live_ से। key पर verification.pan.read scope होना ज़रूरी है। अगर key सही है पर scope नहीं, तो 403 मिलेगा। Keys, scopes और IP allowlist के बारे में API authentication का पेज देखिए।

body के fields

name वैकल्पिक है, पर मेरी सलाह है कि KYC जैसे काम में इसे हमेशा भेजिए। इसके बिना आपको nameMatchResult और nameMatchScore नहीं मिलेंगे, और तब आप सिर्फ़ यह जान पाएँगे कि नंबर मौजूद है, यह नहीं कि वह इसी आदमी का है।

एक पूरा उदाहरण

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/pan" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F","name":"Rahul Kumar"}'

यहाँ STAMPMITRA_API_KEY एक environment variable है। key को कोड या git में सीधे मत लिखिए। इस गाइड में सारे उदाहरण दस्तावेज़ का sample PAN ABCDE1234F और sample नाम "Rahul Kumar" इस्तेमाल करते हैं। ये काल्पनिक मान हैं, किसी असली व्यक्ति के नहीं। टेस्टिंग में भी असली लोगों के PAN अपने लॉग या टिकट में मत चिपकाइए।

अगर आप पूरा endpoint reference एक जगह देखना चाहते हैं तो PAN verification की reference और PAN product पेज देखें।

response के हर field का क्या मतलब है?

सफल call पर नीचे जैसा JSON आता है। यह API reference का असली उदाहरण है।

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

fields की तालिका

दो बारीकियाँ। पहली, nameMatchScore उदाहरण में स्ट्रिंग "100" है, संख्या नहीं। इसे तुलना से पहले Number(...) या int(...) में बदलिए। दूसरी, दस्तावेज़ में panStatusCode का सिर्फ़ E और aadhaarSeedingStatus का सिर्फ़ y वाला उदाहरण दिया गया है। दूसरे मानों की पूरी सूची reference में नहीं दी गई, इसलिए अपने कोड में सिर्फ़ इन्हीं दो मानों के भरोसे else वाली शाखा मत लिखिए। जो मान आप पहचानते नहीं, उन्हें "मैन्युअल रिव्यू" की तरफ़ भेजिए और बाद में reference में देखकर नियम पक्का कीजिए।

referenceId को सही जगह रखिए

referenceId हर सफल call में आता है, नकारात्मक नतीजे (valid: false) में भी। इसे अपने आवेदन के रिकॉर्ड के साथ सेव कीजिए। पर यह idempotency key नहीं है, यानी इसे भेजकर आप दोबारा call को रोक नहीं सकते। एक ही PAN पर बार-बार call करेंगे तो हर call अलग गिनी जाएगी।

पहली call: cURL, Node.js और Python में

ऊपर cURL का उदाहरण आ चुका है। अब सर्वर कोड देखिए। दोनों उदाहरण में तीन बातें साझा हैं: key environment से आती है, PAN पहले साफ़ और जाँचा जाता है, और error की जगह एक सीधा नतीजा लौटाया जाता है जिससे आपका फॉर्म आगे फैसला कर सके।

Node.js (Node 18 या उससे ऊपर)

const BASE = "https://api-b2b.stampmitra.in";
const PAN_REGEX = /^[A-Z]{5}[0-9]{4}[A-Z]$/;

async function verifyPan(rawPan, name) {
  const pan = String(rawPan ?? "").replace(/\s+/g, "").toUpperCase();
  if (!PAN_REGEX.test(pan)) {
    return { ok: false, reason: "FORMAT" };
  }

  const res = await fetch(`${BASE}/v1/verify/pan`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STAMPMITRA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(name ? { pan, name } : { pan }),
  });

  const body = await res.json();
  if (!res.ok) {
    // हर error इसी आकार में आता है: { error: { code, message, requestId } }
    return {
      ok: false,
      reason: body?.error?.code ?? "UNKNOWN",
      status: res.status,
      requestId: body?.error?.requestId,
    };
  }
  return { ok: true, data: body };
}

verifyPan("ABCDE1234F", "Rahul Kumar").then((r) => {
  if (r.ok) console.log(r.data.valid, r.data.referenceId);
  else console.log("रुकिए:", r.reason, r.requestId);
});

Python (requests के साथ)

import os
import re
import requests

BASE = "https://api-b2b.stampmitra.in"
PAN_RE = re.compile(r"^[A-Z]{5}[0-9]{4}[A-Z]$")


def verify_pan(raw_pan, name=None):
    pan = "".join(str(raw_pan or "").split()).upper()
    if not PAN_RE.match(pan):
        return {"ok": False, "reason": "FORMAT"}

    payload = {"pan": pan}
    if name:
        payload["name"] = name

    res = requests.post(
        f"{BASE}/v1/verify/pan",
        headers={
            "Authorization": f"Bearer {os.environ['STAMPMITRA_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=15,
    )
    body = res.json()
    if not res.ok:
        err = body.get("error", {})
        return {
            "ok": False,
            "reason": err.get("code", "UNKNOWN"),
            "status": res.status_code,
            "request_id": err.get("requestId"),
        }
    return {"ok": True, "data": body}

Python वाले उदाहरण में timeout=15 जानबूझकर रखा गया है। बिना timeout के कोई धीमी call आपके पूरे worker को अटका सकती है। जो भी भाषा हो, timeout ज़रूर रखिए। Node के साथ सरल तरीका AbortSignal.timeout(15000) को fetch में जोड़ना है।

इन्हीं उदाहरणों का थोड़ा और विस्तृत रूप, दोनों भाषाओं के साथ, Node.js और Python में PAN verify करने वाली गाइड में है। अगर आप AI टूल से कोड लिखवाना चाहते हैं तो Build with AI पेज पर तैयार prompt मिलते हैं।

नाम के मिलान (nameMatchResult) को फॉर्म के फैसले में कैसे बदलें?

valid: true मिलने के बाद भी आवेदन तुरंत पास नहीं होना चाहिए। असली सवाल यह है कि यूज़र ने जो नाम लिखा, वह रिकॉर्ड के नाम से कितना मिलता है। यहीं ज़्यादातर टीमें या तो बहुत सख़्त हो जाती हैं (और सही यूज़र को बेवजह लौटा देती हैं) या बहुत ढीली (और गलत लोगों को निकल जाने देती हैं)।

नाम क्यों नहीं मिलते

भारत में एक ही आदमी का नाम अलग-अलग जगह अलग तरह से लिखा मिलता है: "Rahul Kumar", "Kumar Rahul", "R. Kumar", या बीच का नाम जोड़ा हुआ। शादी के बाद उपनाम बदलना, spelling की भिन्नता और ट्रांसलिटरेशन (हिंदी से अंग्रेज़ी) की चूकें भी आम हैं। इसलिए सीधा == की जाँच काम नहीं करती और API मिलान का एक स्कोर देती है।

तीन-रास्ते का नियम

नीचे की तालिका एक शुरुआती नियम है। इसमें स्कोर की सीमा (threshold) आपके अपने जोखिम पर निर्भर है। StampMitra का दस्तावेज़ कोई "सही" threshold तय नहीं करता, इसलिए इसे अपने डेटा देखकर कसिए।

कोड में यह कुछ ऐसा दिखेगा:

function decide(data, minScore = 80) {
  if (!data.valid) return "REVIEW";
  const score = Number(data.nameMatchScore);
  if (data.nameMatchResult === "MATCH" && score >= minScore) return "APPROVE";
  if (Number.isFinite(score) && score > 0) return "ASK_AGAIN";
  return "REVIEW";
}

यहाँ 80 सिर्फ़ उदाहरण है, कोई सिफ़ारिश नहीं। पहले कुछ सौ असली नतीजे देखिए, कितने सही यूज़र किस स्कोर पर अटके, फिर threshold तय कीजिए।

यूज़र को क्या दिखाएँ

"आपका नाम PAN से नहीं मिलता" कहना काफ़ी नहीं है। यूज़र को वजह और अगला कदम बताइए: "कृपया नाम वैसा ही लिखें जैसा आपके PAN कार्ड पर छपा है।" पर रिकॉर्ड का असली registeredName पूरा स्क्रीन पर वापस मत दिखाइए। इससे कोई भी दूसरों के PAN डालकर उनके नाम पता कर सकता है। अगर दिखाना ही हो तो सिर्फ़ मास्क किया हुआ रूप दिखाइए।

और हाँ, नाम की तुलना सिर्फ़ तकनीकी चीज़ नहीं है, यह आपके business का नियम है। अपनी compliance टीम से तय करा लीजिए कि कौन-सा स्कोर किस रास्ते पर जाएगा।

errors: 400, 401, 403, 402, 429 और 502

इस API का हर error एक ही आकार में आता है: { "error": { "code", "message", "requestId" } }। यानी आपको हर status के लिए अलग parsing नहीं लिखनी पड़ती। requestId को लॉग कीजिए, सपोर्ट को यही चाहिए होगा।

status codes की तालिका

कौन-से error पर retry करें, कौन-से पर नहीं

400, 401, 403 और 402 आपकी तरफ़ की समस्याएँ हैं। इन पर बार-बार retry करने से कुछ नहीं बदलेगा, पहले कारण ठीक कीजिए। 429 और 502 अस्थायी हैं। इन पर exponential backoff के साथ दो-तीन बार retry ठीक है: पहले 1 सेकंड, फिर 2, फिर 4। 429 पर ख़ास ध्यान रखिए कि आपका retry खुद नई भीड़ न बन जाए।

429 के दो चेहरे

सपोर्ट पेज के अनुसार 429 दो वजहों से आ सकता है: rate limit, या आपका sandbox quota। दोनों में एक जैसा दिखता है, पर इलाज अलग है। rate limit में थोड़ा रुकना काफ़ी है। Sandbox quota खत्म हुआ हो तो रुकने से कुछ नहीं होगा। उस स्थिति के लिए नीचे sandbox वाला सेक्शन और error handling की गाइड देखिए।

नतीजा नकारात्मक हो तो वह error नहीं है

एक आम उलझन: valid: false कोई HTTP error नहीं है। यह 200 के साथ आया एक पूरा, गिना गया नतीजा है, जिसमें referenceId भी है। अगर आपका कोड सिर्फ़ res.ok देखकर "सब ठीक" मान ले, तो अमान्य PAN वाले आवेदन भी निकल जाएँगे। हमेशा valid को अलग से जाँचिए।

सर्वर पर पूरा flow कैसे बैठाएँ: सहज क्रेडिट का worked उदाहरण

अब तक के टुकड़ों को जोड़कर देखते हैं। सहज क्रेडिट का आवेदन-फॉर्म तीन चरणों में चलता है: यूज़र PAN और नाम भरता है, सर्वर verification करता है, और नतीजे के हिसाब से अगला पन्ना खुलता है।

चरण 1: फॉर्म से सर्वर तक

ब्राउज़र आपके अपने endpoint, मान लीजिए /api/kyc/pan, पर PAN और नाम भेजता है। StampMitra की key इस endpoint के पीछे सर्वर में बैठी है। ब्राउज़र को कभी StampMitra का पता या key नहीं दिखनी चाहिए। आपका सर्वर यूज़र का लॉगिन-सत्र जाँचता है, फिर cleanPan और regex चलाता है, और तभी बाहर की call करता है। इस क्रम का फ़ायदा यह है कि कोई भी बिना लॉगिन के आपकी key के पैसे खर्च नहीं करवा सकता।

चरण 2: एक ही यूज़र की बार-बार calls

मान लीजिए यूज़र "सबमिट" पर तीन बार क्लिक कर देता है। अगर आपने कुछ नहीं किया तो तीन calls जाएँगी और तीनों गिनी जाएँगी। referenceId idempotency key नहीं है, इसलिए यह सुरक्षा आपको ख़ुद बनानी होगी। सबसे आसान तरीका है कि सबमिट के बाद बटन तुरंत बंद करें, और सर्वर पर एक छोटा नियम रखें: एक ही आवेदन के लिए एक ही PAN पर कुछ मिनट के भीतर आया दूसरा अनुरोध, पुराना नतीजा लौटा दे। यह नियम आपके database में आवेदन के साथ referenceId और नतीजा रखकर बन जाता है।

चरण 3: नतीजे का रास्ता

सर्वर decide जैसे फ़ंक्शन से तीन में से एक फैसला निकालता है। "APPROVE" पर आवेदन अगले पन्ने पर जाता है और database में referenceId, valid, मिलान का नतीजा और तारीख़ दर्ज होती है। "ASK_AGAIN" पर फॉर्म वही पन्ना दोबारा दिखाता है, इस बार नाम के खाने के नीचे सुझाव के साथ। "REVIEW" पर आवेदन ऑपरेशंस की कतार में चला जाता है और यूज़र को बताया जाता है कि जाँच में थोड़ा समय लगेगा।

दो छोटे परिदृश्य

परिदृश्य एक: सही यूज़र, थोड़ा अलग नाम। यूज़र ने नाम "Rahul Kumar" लिखा और रिकॉर्ड में RAHUL KUMAR है। अक्षरों का बड़ा-छोटा होना फ़र्क़ नहीं डालता, और जैसा ऊपर के उदाहरण में दिखा, मिलान MATCH और स्कोर "100" आता है। आवेदन सीधा आगे बढ़ता है।

परिदृश्य दो: format ठीक, पर नंबर रिकॉर्ड में नहीं। यूज़र ने किसी तरह एक गलत पर ढाँचे में सही नंबर डाल दिया। फॉर्म ने इसे जाने दिया क्योंकि ढाँचा सही था। API का जवाब valid: false के साथ आता है। आपके कोड को इसे error नहीं, एक सामान्य नतीजे की तरह लेना है: यूज़र को बताइए कि PAN रिकॉर्ड में नहीं मिला, कृपया कार्ड देखकर दोबारा लिखें। अगर दोबारा भी यही हो तो आवेदन मैन्युअल रिव्यू में भेजिए। ध्यान रखिए कि यह भी एक गिनी गई call है, इसलिए दोबारा कोशिशों की संख्या दो-तीन तक सीमित रखिए।

चरण 4: बाद में क्या सेव रखें

कई टीमें हर call का पूरा JSON अपने database में डाल देती हैं और फिर महीनों बाद उसे हटाना भूल जाती हैं। बेहतर है कि आप शुरू में तय कर लें कि आपको कौन-से fields चाहिए और कितने समय तक। ऑडिट के लिए referenceId, जाँच की तारीख़ और फैसला (APPROVE, ASK_AGAIN, REVIEW) आम तौर पर काम की चीज़ें हैं। रखने की अवधि का फैसला आपके कानूनी दायित्वों से होता है, इसलिए वहाँ अपने सलाहकार से पूछिए।

चरण 5: धीमी या अटकी call का इलाज

बाहरी call कभी अटक सकती है। इसलिए सर्वर में timeout रखिए, और यूज़र को स्पिनर के साथ एक सीमित समय तक ही इंतज़ार कराइए। अगर timeout हो गया तो आवेदन को "जाँच बाकी" की स्थिति में रखिए और बाद में पीछे से (background job) फिर से कोशिश कीजिए, ताकि यूज़र को दोबारा सब कुछ न भरना पड़े। ऐसे में जो call पूरी हो चुकी हो पर आपको जवाब न मिला हो, उसका referenceId आपके पास नहीं होगा। इसलिए अपनी तरफ़ का एक अलग id, जैसे आवेदन संख्या, हमेशा अपने लॉग में साथ लिखिए ताकि सपोर्ट से बात करते समय समय और आवेदन मिलाया जा सके।

सहमति (consent) और डेटा संभालने के नियम

PAN एक पहचान-संख्या है और नाम के साथ मिलकर संवेदनशील व्यक्तिगत डेटा बन जाती है। भारत में व्यक्तिगत डेटा के लिए Digital Personal Data Protection Act, 2023 बना है। यहाँ इसे सामान्य जानकारी के स्तर पर बताया जा रहा है, धाराओं के हवाले के बिना। आपके मामले में वह कैसे लागू होता है, यह किसी योग्य वकील से पूछिए, क्योंकि नियम और उनकी अधिसूचित तारीखें बदलती रहती हैं।

सहमति और उद्देश्य

यूज़र का PAN जाँचने से पहले उसे साफ़ शब्दों में बताइए कि PAN क्यों माँगा जा रहा है और उसे किस काम में इस्तेमाल किया जाएगा, जैसे "आपका खाता खोलने के लिए पहचान की जाँच"। सहमति का बटन पहले से टिक (pre-checked) मत रखिए। जिस मकसद के लिए सहमति ली, उसी मकसद के लिए डेटा इस्तेमाल कीजिए। उदाहरण के लिए, KYC के लिए लिया गया PAN बाद में मार्केटिंग सूची में मत डालिए।

जितना ज़रूरी, उतना ही रखिए

दस्तावेज़ के response में नाम, पिता का नाम और आधार से जुड़ाव की जानकारी तक आती है। हर चीज़ अपने database में सेव करना ज़रूरी नहीं। सोचिए कि आपके काम के लिए असल में क्या चाहिए। कई टीमों के लिए इतना काफ़ी होता है: referenceId, valid, मिलान का नतीजा, lastUpdatedAt और जाँच की तारीख। बाकी को सहेजना है या नहीं, यह आपके कानूनी दायित्व और रखने की अवधि पर निर्भर है। जो डेटा रखने की वजह खत्म हो जाए, उसे मिटाने की प्रक्रिया पहले से तय कीजिए।

व्यवहार में यह चेकलिस्ट काम आती है

• API key सिर्फ़ सर्वर पर, environment variable या secret manager में रखें। browser, मोबाइल ऐप या सार्वजनिक repo में कभी नहीं।
• लॉग में पूरा PAN न छापें। ज़रूरत हो तो सिर्फ़ आख़िरी चार अक्षर और referenceId रखें।
• PAN को database में सेव करना हो तो पहुँच सीमित रखें और एन्क्रिप्शन पर विचार करें।
• नाम और PAN वाली स्क्रीनशॉट या टिकट सपोर्ट में भेजते समय मान मास्क करें।
• डेटा लीक या गलत इस्तेमाल की स्थिति में क्या होगा, इसकी एक लिखित प्रक्रिया रखें।

StampMitra की ओर से Developer Privacy Policy, Data Processing Addendum और API Security Policy अलग पेजों पर हैं। इन्हें अपनी टीम के साथ पढ़ लीजिए, ताकि आपको पता रहे कि कौन-सा हिस्सा किसकी ज़िम्मेदारी है। साथ ही API Acceptable Use Policy देखिए कि API का क्या उपयोग मना है।

Sandbox में टेस्टिंग कैसे करें?

Sandbox आपकी integration को बिना पैसे खर्च किए परखने की जगह है। मुफ़्त अकाउंट बनाकर आपको तुरंत sk_test_ वाली key मिलती है। इसके लिए क्रेडिट कार्ड या किसी मैन्युअल अनुमोदन की ज़रूरत नहीं है। key सिर्फ़ एक बार दिखती है, इसलिए उसी समय किसी सुरक्षित जगह रख लीजिए। नई keys डैशबोर्ड के API Keys सेक्शन से बन सकती हैं।

sandbox क्या देता है

Sandbox की call sandbox डेटा पर चलती है और आपके wallet से पैसे नहीं काटती। फिर भी वह मीटर होती है और audit-log में दर्ज होती है। एक बात ध्यान से पढ़िए: सपोर्ट पेज के अनुसार 429 का एक कारण आपका "lifetime sandbox quota" भी है। यानी sandbox की गिनती की एक सीमा है। इसलिए sandbox में भी बेवजह लूप या बार-बार वही call मत चलाइए। जो सीमा आपके खाते पर लागू है, उसके लिए डैशबोर्ड और सपोर्ट देखिए, कोई संख्या यहाँ से मत मान लीजिए।

किन चीज़ों की टेस्टिंग करें

सिर्फ़ "सफल call चली" देखकर मत रुकिए। नीचे की सूची में से हर एक को अपने कोड के लिए आज़माइए।

एक सुझाव: अपने सर्वर में verification को एक छोटे अलग फ़ंक्शन में रखिए, जैसे ऊपर verifyPan। फिर टेस्ट में उसकी जगह नकली (mock) जवाब रखकर बाकी flow के सारे रास्ते जाँचे जा सकते हैं, बिना sandbox quota खर्च किए। वही पहली call quickstart में पाँच मिनट में पूरी हो जाती है, और Postman पेज पर भी देख सकते हैं।

Sandbox और production की keys में फर्क को विस्तार से sandbox बनाम production API keys की गाइड में समझाया गया है।

Production में जाने से पहले की चेकलिस्ट

Sandbox में सब ठीक चल रहा हो तो भी production में कुछ नई चीज़ें आती हैं: असली पैसे, असली लोग और असली डेटा।

कदम-दर-कदम

1. Production access के लिए आवेदन करें। डैशबोर्ड से आवेदन होता है। production key बनाने के लिए organization का KYC-approved होना ज़रूरी है, इसलिए इसे आख़िरी दिन पर मत छोड़िए।
2. Wallet टॉप-अप करें। production में हर सफल call आपके API credit wallet से कटती है। wallet में पैसे कम पड़ने पर 402 आएगा, और तब आपके यूज़र की ऑनबोर्डिंग रुक सकती है। इसलिए कम बैलेंस की चेतावनी का इंतज़ाम रखिए।
3. नई sk_live_ key बनाइए और उसे अपने secret manager में रखिए। sandbox वाली key production में काम नहीं करेगी, और सुरक्षा के लिए उलटा भी नहीं होना चाहिए।
4. स्कोप और IP allowlist कसिए। key को सिर्फ़ verification.pan.read जितना ही अधिकार दीजिए। संवेदनशील scopes पर IP allowlist भी लगाई जा सकती है।
5. Rate limit का हिसाब लगाइए। reference के उदाहरण में 60 requests प्रति 60 सेकंड प्रति endpoint का संदेश है। अगर आपका ट्रैफ़िक किसी सुबह अचानक बढ़ सकता है, जैसे कोई कैंपेन, तो calls को कतार (queue) में रखिए।
6. लॉग और अलर्ट लगाइए। 401, 402, 403, 429 और 502 की गिनती देखिए। 402 और 401 की अचानक बढ़ोतरी आम तौर पर wallet या key की समस्या होती है।

कीमत

Production में हर सफल call पर शुल्क लगता है, जो इस समय ₹5 प्रति call है। चालू दर के लिए हमेशा pricing पेज देखिए, क्योंकि दरें बदल सकती हैं। याद रखिए कि valid: false वाला नतीजा भी पूरा किया गया verification है और गिना जाता है। इसलिए format की जाँच अपने फॉर्म में करके 400 वाली बेकार calls घटाइए। ध्यान रहे कि दस्तावेज़ के अनुसार usage सिर्फ़ सफल response के बाद दर्ज होती है और wallet तभी कटता है, इसलिए 400, 401 जैसे error पर शुल्क नहीं बताया गया है।

launch के दिन

पहले दिन कम ट्रैफ़िक से शुरू कीजिए, जैसे कुछ चुने हुए यूज़र। पहले कुछ दर्जन असली नतीजे ख़ुद देखिए। अगर नाम के मिलान वाला नियम बहुत लोगों को रोक रहा है तो threshold वहीं सुधारिए। जब तक आपको भरोसा न हो जाए, मैन्युअल रिव्यू का रास्ता खुला रखिए।

Troubleshooting: "वेरिफिकेशन फेल हो रहा है" तो कहाँ देखें?

जब कुछ गड़बड़ हो तो हड़बड़ी में कोड बदलने से पहले नीचे के क्रम में चलिए। ज़्यादातर समस्याएँ पहले तीन कदमों में निकल आती हैं।

कदम 1: HTTP status देखिए

हर समस्या का पहला सुराग status code है। 400 है तो PAN का format या body की गड़बड़ी। 401 है तो key या header। 403 है तो scope। 402 है तो wallet। 429 है तो गति या quota। 502 है तो पीछे की सेवा। ऊपर के errors वाले सेक्शन की तालिका इसी के लिए है।

कदम 2: ज़्यादा आम कारण

• "सब ठीक है पर हमेशा 401": अक्सर header में Bearer के बाद खाली स्थान छूट जाता है, या key के साथ नई पंक्ति (\n) चिपक कर आ जाती है। environment variable पढ़ते समय .trim() लगाइए।
• "sandbox में चला, production में 401": production में अब भी sk_test_ key भेज रही है। जाँचिए कि deploy वाले environment में कौन-सी key है।
• "403 आ रहा है": key बन गई पर verification.pan.read scope उस पर नहीं चढ़ा।
• "कभी 400 कभी ठीक": यूज़र का PAN कभी छोटे अक्षरों में या space के साथ आता है। cleanPan जैसा साफ़ करने वाला फ़ंक्शन हर जगह लगाइए।
• "नाम बार-बार मेल नहीं खा रहा": यूज़र सिर्फ़ पहला नाम या उपनाम पहले लिख रहा है। फॉर्म में नाम का एक ही पूरा खाना रखिए और बताइए कि PAN कार्ड वाला नाम लिखें।
• "बीच-बीच में 502": पीछे की सेवा अस्थायी रूप से नहीं मिली। backoff के साथ retry चलाइए और यूज़र के लिए "थोड़ी देर बाद कोशिश करें" का संदेश रखिए।
• "429 अचानक आने लगा": अगर आप sandbox में हैं तो quota की संभावना देखिए, और अगर लूप में calls हो रही हैं तो उन्हें धीमा कीजिए।

कदम 3: डिबग के लिए सही जानकारी

सपोर्ट से बात करने से पहले ये चीज़ें तैयार रखिए: error का requestId या सफल call का referenceId, call का समय, status code, और आपने कौन-सा environment (sandbox या production) इस्तेमाल किया। PAN या पूरा नाम ईमेल में मत लिखिए। संपर्क के लिए सपोर्ट पेज देखिए या [email protected] पर लिखिए।

आम गलतियाँ, जो हर टीम एक बार करती है

पहली, API key को React या मोबाइल ऐप के कोड में रख देना। जो कुछ भी browser में पहुँचता है, उसे कोई भी निकाल सकता है। दूसरी, res.ok को ही "सफल verification" मान लेना और valid न देखना। तीसरी, नाम का मिलान === से करना। चौथी, 400 पर अपने आप retry चलाना, जो हर बार वही गलती दोहराएगा। पाँचवीं, लॉग में पूरा PAN और नाम छाप देना। छठी, सिर्फ़ सफल रास्ते (happy path) की टेस्टिंग करना। सातवीं, referenceId को सेव न करना, जिससे बाद में विवाद होने पर कोई सबूत नहीं रहता।

अगर आपकी समस्या एक error code से आगे की है तो API errors और उनके सँभालने की गाइड में और उदाहरण हैं।

कब PAN API इस्तेमाल करें और कब नहीं?

हर जगह PAN verification लगा देना ठीक नहीं। नीचे के नियम बताते हैं कि कब यह सही उपकरण है।

इस्तेमाल करें, जब

• आप व्यक्तियों या फ़र्मों की ऑनबोर्डिंग कर रहे हैं और आपको दस्तावेज़ी जाँच चाहिए, जैसे लोन, निवेश, फ़्रीलांसर पेआउट या विक्रेता जोड़ना।
• फॉर्म की गलत और नकली एंट्री ऑपरेशंस टीम का समय खा रही है और आप शुरुआती छँटाई अपने आप करना चाहते हैं।
• आपको ऑडिट के लिए हर जाँच का एक referenceId वाला रिकॉर्ड चाहिए।
• आपको नाम का मिलान स्कोर चाहिए, सिर्फ़ "नंबर है या नहीं" नहीं।

इस्तेमाल मत करें (या अकेले मत करें), जब

• आपको यह पक्का करना है कि सामने वाला इंसान ही असली मालिक है। इसके लिए PAN की जाँच अकेली काफ़ी नहीं है।
• आपका काम ऐसा है जहाँ PAN की ज़रूरत ही नहीं है। जो डेटा चाहिए नहीं, उसे माँगना खुद एक जोखिम है।
• आप कंपनी या व्यवसाय की जाँच कर रहे हैं, यानी GSTIN, CIN या Udyam चाहिए। इसके लिए GSTIN verification की गाइड और व्यवसाय की जाँच वाली गाइड देखिए।
• आपका user base बहुत छोटा और अनियमित है और कुछ आवेदन हाथ से जाँचना सस्ता और आसान है।

फिनटेक KYC में PAN की जगह

PAN अक्सर KYC की पहली कड़ी होती है, पूरी नहीं। नियमित संस्थाओं (जैसे NBFC) की ज़रूरतें अलग होती हैं और उन्हें अपने नियामक के निर्देशों के हिसाब से तय करना होता है। इस पर फिनटेक और NBFC के लिए KYC API वाला use case पढ़ सकते हैं। नियमों का अर्थ निकालने के लिए अपने सलाहकार से ज़रूर पूछिए।

जब PAN से आगे बढ़ना हो

कभी-कभी आपको PAN से जुड़े और रिकॉर्ड भी चाहिए होते हैं। इसके लिए दस्तावेज़ में PAN to GSTIN और PAN to Udyam जैसे अलग endpoints हैं, जिनके अपने scopes हैं। पूरी सूची Verification APIs के पेज पर है।

StampMitra आपकी कैसे मदद करता है

StampMitra एक निजी LegalTech प्लेटफ़ॉर्म है, जिसे Bani Global Industries LLP (LLPIN ACI-6373) चलाती है। यह सरकारी संस्था या कानूनी फ़र्म नहीं है, और इसकी कोई भी बात कानूनी सलाह नहीं है। आज StampMitra Developers पर आपको PAN verification के लिए ये चीज़ें मिलती हैं।

एक असली endpoint: POST /v1/verify/pan, जो verification.pan.read scope के साथ चलता है। यही endpoint format की जाँच ऊपर से करता है, यानी गलत PAN बिना बेकार verification के सीधे 400 में लौट जाता है। हर सफल जवाब में StampMitra का अपना referenceId आता है, जिसे आप अपने रिकॉर्ड और सपोर्ट के लिए रख सकते हैं। हर error एक ही आकार में आता है, error.code, error.message और error.requestId के साथ, इसलिए आपकी error-handling एक जगह लिखी जा सकती है।

Sandbox में आप sk_test_ key से मुफ़्त में शुरू कर सकते हैं, जो wallet से पैसे नहीं काटती। Production में जाने के लिए आपको KYC-approved organization चाहिए और wallet में बैलेंस। पूरे flow को आप quickstart में पाँच मिनट में चला सकते हैं, और बाद में SDKs का पेज और MCP का पेज भी देख सकते हैं। keys पर IP allowlist और scopes का नियंत्रण भी उपलब्ध है। StampMitra की निजता, डेटा प्रोसेसिंग और सुरक्षा की नीतियाँ legal पेज पर एक जगह हैं।

एक ईमानदार सीमा भी बताना ज़रूरी है। PAN API दस्तावेज़ी जाँच देती है, व्यक्ति की पहचान की गारंटी नहीं। नाम के मिलान का threshold आपको अपने जोखिम के हिसाब से ख़ुद तय करना होगा। और दस्तावेज़ में panStatusCode जैसे कुछ fields के सारे संभावित मानों की सूची फ़िलहाल नहीं है, इसलिए अनजान मान को मैन्युअल रिव्यू में भेजना सुरक्षित है। कीमतें समय के साथ बदल सकती हैं और चालू दर pricing पेज पर दिखती है।

आगे की योजनाओं की बात करें तो, हमारा इरादा डेवलपर अनुभव को और आसान बनाने का है: और भाषाओं में उदाहरण और हिंदी में अधिक दस्तावेज़। ये योजनाएँ हैं, वादे नहीं, और तारीख़ें तय नहीं हैं। जो आज उपलब्ध है, वह ऊपर के हिस्सों में बताया गया है। अगर आपको किसी चीज़ की कमी खटके तो हमें [email protected] पर बताइए। आपकी असली ज़रूरतें ही तय करती हैं कि अगला काम क्या होगा। एक बार quickstart की call चलाकर देखिए और फिर अपने फॉर्म में जोड़िए। शुरुआत छोटी रखिए: पहले सिर्फ़ sandbox, फिर चुने हुए यूज़र, फिर पूरा ट्रैफ़िक।

API reference एक नज़र में

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

अक्सर पूछे जाने वाले सवाल