फिनटेक और NBFC के लिए KYC API: drop-off से automation तक

मुख्य बातें

• KYC API नंबरों की जाँच तेज़ और automatic बनाती है, लेकिन KYC compliance की ज़िम्मेदारी regulated संस्था की ही रहती है। API का नतीजा आपकी policy के भीतर एक input है।
• StampMitra की verification श्रेणी में PAN, GSTIN, Vehicle RC, Voter ID, Driving Licence, Passport, CIN, Udyam, PAN to GSTIN, PAN to Udyam और Bank Account शामिल हैं। सब POST /v1/verify/... के रूप में हैं।
• हर call में Authorization: Bearer <api-key> चाहिए। sandbox key sk_test_... और production key sk_live_... होती है, और हर endpoint का अपना scope होता है, जैसे verification.pan.read।
• नकारात्मक नतीजा (valid: false या found: false) भी पूरा और billable verification है। इसे "error" मानकर बार-बार retry न करें।
• हर सफल call पर referenceId (format SMV-YYYYMMDD-XXXXXXX) मिलता है। इसे अपने audit रिकॉर्ड में रखें, लेकिन यह idempotency key नहीं है।
• API का जवाब सीधे approve या reject में न बदलें। तीन रास्ते रखें: अपने आप आगे, manual review, और अस्वीकार।
• ग्राहक की सहमति, ज़रूरत भर का डेटा और सीमित अवधि तक रखना, ये DPDP Act 2023 के संदर्भ में सामान्य अच्छी आदतें हैं। विशेष सलाह के लिए अपने कानूनी सलाहकार से पूछें।

पूरी कहानी कहाँ से शुरू होती है: drop-off का हिसाब

मान लीजिए "सहज क्रेडिट" नाम की एक काल्पनिक लोन ऐप है और उसकी प्रोडक्ट मैनेजर का नाम नेहा है। ऐप पर पर्सनल लोन के लिए आवेदन करने वाला ग्राहक पहले अपना मोबाइल नंबर डालता है, फिर PAN, फिर बैंक खाता। पहले संस्करण में पीछे सब कुछ हाथ से होता था। ग्राहक PAN कार्ड की फोटो खींचकर अपलोड करता, ऑपरेशंस टीम का कोई सदस्य उसे देखकर पोर्टल पर मिलाता, और अगले दिन ग्राहक को SMS जाता कि "आपका आवेदन प्रक्रिया में है"।

नेहा ने funnel देखा तो पैटर्न साफ़ था। जो लोग फोटो अपलोड वाली स्टेप तक पहुँचे, उनमें से बहुत-से वहीं रुक गए। वजह छोटी-छोटी थीं: धुंधली फोटो, ग़लत टाइप किया हुआ नंबर, और "कल बताएँगे" वाली चुप्पी जिसमें ग्राहक दूसरी ऐप पर चला गया। यहाँ हम कोई आँकड़ा नहीं दे रहे, क्योंकि हर ऐप का drop-off अलग होता है। आपको अपने ही funnel में देखना होगा कि किस स्टेप पर कितने लोग रुकते हैं।

नेहा की टीम ने तीन सवाल पूछे। पहला: कौन-से check सिर्फ़ "यह नंबर असली है या नहीं" तक सीमित हैं, जिन्हें मशीन तुरंत कर सकती है? दूसरा: कौन-से check में इंसान का फ़ैसला चाहिए? तीसरा: जो कुछ भी हम करें, उसका सबूत और रिकॉर्ड कैसे बचा रहे? इन तीनों सवालों के जवाब पूरे लेख का ढाँचा हैं।

Manual जाँच की छिपी क़ीमत

हाथ की जाँच में सिर्फ़ तनख्वाह का ख़र्च नहीं होता। ग़लती की गुंजाइश, अलग-अलग कर्मचारी का अलग मानदंड, और रिकॉर्ड का बिखरा होना भी जुड़ता है। API आने पर हर ग्राहक पर वही नियम लगता है और हर call का referenceId बचा रहता है। इसका मतलब यह नहीं कि इंसान की ज़रूरत ख़त्म हो गई। इंसान अब उस जगह लगता है जहाँ उसकी सचमुच ज़रूरत है।

क्या API check का मतलब है कि हम KYC-compliant हो गए?

नहीं, और यह वाक्य इस लेख का सबसे ज़रूरी हिस्सा है, इसलिए इसे अलग से खोलते हैं।

RBI की Master Direction (Know Your Customer Direction, 2016) सभी RBI-regulated संस्थाओं पर लागू होती है, जिनमें बैंक और NBFC शामिल हैं। RBI की वेबसाइट पर दिखने वाले संस्करण के अनुसार यह direction संस्थाओं से बोर्ड से मंज़ूर KYC policy माँगती है, जिसमें ग्राहक स्वीकार करने के नियम, risk management, ग्राहक की पहचान और transaction की निगरानी शामिल हैं। ग्राहकों को low, medium और high risk में बाँटना, और रिकॉर्ड तय अवधि तक रखना भी उसी ढाँचे का हिस्सा है। यह जानकारी हमने RBI के पेज से 16 अक्टूबर 2026 को पढ़ी, और वहाँ दिखा संस्करण "Updated as on July 12, 2018" था। इसके बाद के संशोधन आ चुके हो सकते हैं, इसलिए बाध्यकारी नियम हमेशा RBI की ताज़ा वेबसाइट और अपने compliance विभाग से देखें।

API क्या देती है और क्या नहीं

API यह बताती है कि दिए गए नंबर के बारे में रिकॉर्ड क्या कहता है। जैसे PAN valid है या नहीं, और नाम मिलता है या नहीं। लेकिन ये बातें API अपने-आप तय नहीं करती:

• आपकी policy में किस ग्राहक के लिए कौन-सा दस्तावेज़ पर्याप्त है।
• ग्राहक सचमुच वही इंसान है या नहीं (चेहरे का मिलान, liveness, वीडियो आधारित प्रक्रिया)। ये चीज़ें StampMitra की मौजूदा verification सूची में नहीं हैं।
• ग्राहक risk category में कहाँ आता है।
• रिकॉर्ड कितने समय तक और कहाँ रखे जाएँ।
• संदिग्ध लेन-देन की निगरानी और आगे की रिपोर्टिंग।

इसलिए एक सुरक्षित वाक्य यह होगा: "हम अपनी KYC policy के तहत कुछ चरणों को API से automate करते हैं।" यह वाक्य ग़लत होगा: "StampMitra का इस्तेमाल करने से हम KYC-compliant हैं।" StampMitra, Bani Global Industries LLP द्वारा चलाया जाने वाला एक निजी LegalTech प्लेटफ़ॉर्म है। यह सरकारी एजेंसी या कानूनी सलाहकार फ़र्म नहीं है, और इस लेख की कोई बात कानूनी सलाह नहीं है।

StampMitra की कौन-सी verification API किस काम की है?

अब मशीनरी की तरफ़ चलते हैं। StampMitra की verification श्रेणी में ग्यारह उत्पाद हैं, और हर एक अपना अलग endpoint और अलग scope रखता है। नीचे की तालिका src/data/api-products.ts में दर्ज असली path और scope के हिसाब से है।

हर endpoint का पूरा schema आप PAN के docs पेज और बाक़ी उत्पादों के पेजों पर देख सकते हैं, और सभी उत्पादों की सूची products पेज पर है। इनके दाम के लिए यह लेख कोई रक़म नहीं लिखता, क्योंकि दाम बदल सकते हैं। ताज़ा दर हमेशा pricing पेज पर देखें।

लोन ऐप के लिए इनमें असल में कौन-से काम के हैं

नेहा की ऐप दो तरह के ग्राहक संभालती है: वेतनभोगी या स्वरोज़गार व्यक्ति, और छोटा व्यवसाय। व्यक्ति के लिए PAN, बैंक खाता और ज़रूरत पड़ने पर Voter ID, Driving Licence या Passport काम आते हैं। व्यवसाय के लिए GSTIN, CIN, Udyam और PAN से GSTIN या Udyam खोजने वाले दोनों endpoint। Vehicle RC उस समय काम आता है जब आप वाहन गिरवी रखकर या वाहन पर लोन देते हैं।

ग्राहक के सफ़र में कौन-सा check किस मोड़ पर लगाएँ?

नेहा ने सफ़र को चार पड़ावों में बाँटा, और हर पड़ाव पर एक ही सवाल रखा: "इस मोड़ पर सबसे सस्ता और सबसे तेज़ कौन-सा check है जो आगे की उलझन टाल दे?"

इस क्रम का तर्क सीधा है। सबसे सस्ता और सबसे ज़्यादा काट-छाँट करने वाला check सबसे आगे रखें, ताकि जो आवेदन आगे जा ही नहीं सकते उन पर बाद वाले, ज़्यादा ख़र्चीले check का पैसा न लगे। बैंक खाते की जाँच सबसे आख़िर में रखने का कारण भी यही है: पैसा भेजने से ठीक पहले यह पक्का करना कि रक़म सही जगह जाएगी।

क्रम तय करते समय की एक चेतावनी

यह क्रम आपकी policy के हिसाब से बदल सकता है। कुछ संस्थाएँ बैंक खाता पहले ही माँग लेती हैं ताकि mandate जल्दी बने। कुछ उत्पादों में PAN के बिना आगे बढ़ना ही मना होता है। तालिका एक नमूना है, नियम नहीं। अपना क्रम compliance टीम से तय करवाएँ।

शुरुआत: sandbox key, scope और IP allowlist

पहला क़दम पूरी तरह मुफ़्त है। signup पर एक developer अकाउंट बनाकर आप sandbox में जाँच शुरू कर सकते हैं। स्टैंडर्ड quickstart इस पेज पर है और key बनाने का पूरा मॉडल auth docs में है।

API key कैसी दिखती है

हर protected endpoint के लिए या तो Authorization: Bearer <key> header चाहिए या x-api-key: <key>। Sandbox key sk_test_... से शुरू होती है और production key sk_live_... से। एक अहम बात: environment आपके key से सर्वर तय करता है, आप अपने request में "sandbox" या "live" नहीं भेजते। यानी आप यह फ़र्क़ अपने कोड के भीतर नहीं, key बदलकर करते हैं।

Scope: हर key को सिर्फ़ उतना ही अधिकार

हर key के साथ scopes की एक सूची जुड़ी होती है, जैसे verification.pan.read या orders.create। अगर key वैध है पर उस endpoint का scope उसमें नहीं है, तो आपको 403 और FORBIDDEN कोड वाला जवाब मिलता है। सलाह यह है कि onboarding सर्विस की key में सिर्फ़ वही scopes रखें जो उस सर्विस को चाहिए। बैंक खाता जाँच करने वाली disbursal सर्विस को PAN का scope देने की ज़रूरत नहीं।

IP allowlist

किसी भी key को IP या CIDR सूची तक सीमित किया जा सकता है। हमारे प्लेटफ़ॉर्म पर PAN और RC जैसे संवेदनशील scopes के लिए यह allowlist डिफ़ॉल्ट रूप से माँगी जाती है। इसका मतलब है कि production में आपके सर्वर का स्थिर outbound IP होना चाहिए। अगर आप serverless चलाते हैं, तो NAT gateway के पीछे से call भेजने की योजना पहले बना लें, वरना launch के दिन सबसे पहले 403 दिखेगा।

IP allowlist और लोड का तालमेल

अगर आपका onboarding सर्वर autoscaling में चलता है और हर नया instance अलग IP से निकलता है, तो allowlist वाला key बार-बार 403 देगा। इसका हल यह है कि बाहर जाने वाला ट्रैफ़िक एक स्थिर पते (जैसे NAT) से निकले और वही पता allowlist में जुड़े। यह तैयारी development में नहीं दिखती, इसलिए इसे staging में पहले परखिए।

पहला काम: PAN verify करना

अब कोड की बारी है। PAN नेहा के funnel का पहला दरवाज़ा है, इसलिए हम उसी से शुरू करते हैं। request और response नीचे वही हैं जो API के असली रूप में दर्ज हैं, और PAN नंबर नमूना है, किसी असली व्यक्ति का नहीं।

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

सफल जवाब कुछ ऐसा आता है:

{
  "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"
}

जवाब के कौन-से हिस्से फ़ैसले में काम आते हैं

valid और panStatus बताते हैं कि PAN मौजूद और चालू है या नहीं। nameMatchResult और nameMatchScore तब आते हैं जब आपने request में name भेजा हो, और ये बताते हैं कि भेजा हुआ नाम रिकॉर्ड के नाम से कितना मिलता है। ध्यान दीजिए कि nameMatchScore इस उदाहरण में एक string के रूप में है ("100"), संख्या नहीं, इसलिए तुलना से पहले उसे number में बदलें। type बताता है कि PAN व्यक्ति का है या किसी और संस्था का, जो इस बात की जाँच में काम आता है कि ऐप पर "व्यक्ति" बनकर आने वाले ने कंपनी का PAN तो नहीं दे दिया।

Node.js में

// verify-pan.js (Node 18+)
const API = "https://api-b2b.stampmitra.in";

export async function verifyPan(pan, name) {
  const res = await fetch(`${API}/v1/verify/pan`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STAMPMITRA_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ pan, name }),
  });
  const body = await res.json();
  if (!res.ok) {
    const e = body.error || {};
    throw Object.assign(new Error(e.message), {
      status: res.status, code: e.code, requestId: e.requestId,
    });
  }
  return body;
}

Python में

import os, requests

API = "https://api-b2b.stampmitra.in"

def verify_pan(pan, name=None):
    payload = {"pan": pan}
    if name:
        payload["name"] = name
    r = requests.post(
        f"{API}/v1/verify/pan",
        headers={"Authorization": f"Bearer {os.environ['STAMPMITRA_KEY']}"},
        json=payload,
        timeout=15,
    )
    body = r.json()
    if not r.ok:
        err = body.get("error", {})
        raise RuntimeError(f"{r.status_code} {err.get('code')}: {err.get('message')} ({err.get('requestId')})")
    return body

key को कोड में न लिखें। environment variable या अपनी secrets सेवा से पढ़ें। इसी का एक विस्तृत संस्करण Node.js और Python में PAN verify वाले गाइड में है, और PAN के हर field की बारीकी PAN verification API गाइड में।

disbursal से पहले बैंक खाते की जाँच कैसे करें?

लोन ऐप में सबसे महँगी ग़लती वह है जहाँ रक़म ग़लत खाते में चली जाए। इसलिए नेहा की टीम ने disbursal से ठीक पहले एक rule जोड़ा: खाता सत्यापित हुए बिना पैसा नहीं जाएगा। Bank Account endpoint के लिए 9 से 18 अंकों का खाता नंबर और 11 अक्षर का IFSC चाहिए।

curl -X POST https://api-b2b.stampmitra.in/v1/verify/bank-account \
  -H "Authorization: Bearer sk_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "accountNumber": "000123456789", "ifsc": "ICIC0001234", "name": "Ravi Kumar" }'

{
  "accountNumber": "000123456789",
  "ifsc": "ICIC0001234",
  "bankName": "ICICI Bank",
  "branchName": "Andheri West",
  "accountExists": true,
  "beneficiaryName": "RAVI KUMAR",
  "nameMatch": true,
  "nameMatchScore": 0.95,
  "accountStatus": "ACTIVE"
}

असली fields की पूरी सूची के लिए bank account docs खोलें।

यहाँ नाम-मिलान का स्कोर थोड़ा अलग है

ध्यान दीजिए कि बैंक खाते के जवाब में nameMatch एक boolean है और nameMatchScore एक संख्या (0.95), जबकि PAN में स्कोर string के रूप में आया था ("100") और अलग पैमाने पर। इसी वजह से दोनों के स्कोर को एक ही थ्रेशोल्ड से मत जाँचिए। हर endpoint के लिए अपना नियम रखें और अपने sandbox नमूनों पर उसे परखें।

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

भारतीय नामों में अलग-अलग वर्तनी, बीच के नाम का छूट जाना और संक्षिप्त नाम आम हैं। "रवि कुमार" बैंक में "RAVI KUMAR" हो सकता है और PAN में "RAVINDRA KUMAR"। इसलिए नाम का थोड़ा कम स्कोर आते ही आवेदन को अस्वीकार न करें। उसे manual review वाली क़तार में डालें, जहाँ इंसान दोनों नाम देखकर तय करे। स्कोर की सीमा आपकी risk नीति से तय होगी, हमसे नहीं।

छोटे व्यवसाय को लोन: GSTIN, CIN और Udyam कैसे जोड़ें?

नेहा की ऐप ने कुछ समय बाद MSME लोन भी शुरू किया। यहाँ ग्राहक एक संस्था होती है, और उसके पीछे एक व्यक्ति। व्यवसाय की जाँच में अक्सर तीन सवाल पूछे जाते हैं: क्या यह संस्था रजिस्टर्ड है, क्या वह चालू है, और जो व्यक्ति आवेदन कर रहा है उसका संस्था से क्या रिश्ता है।

GSTIN

GSTIN endpoint में 15 अक्षर का GSTIN और वैकल्पिक businessName जाता है। जवाब में legalName, tradeName, registrationStatus और principalPlaceOfBusiness जैसे fields मिलते हैं। registrationStatus का "Active" होना चालू पंजीकरण का संकेत है। व्यवसाय का पता और आपके पास दिया गया पता मिलाना अलग काम है, जो आपको अपने कोड में करना होगा।

{
  "referenceId": "SMV-20260927-9K21P4",
  "GSTIN": "07AAAAA1111A1Z1",
  "valid": true,
  "legalName": "Jane Doe Enterprises Private Limited",
  "tradeName": "Jane Doe Enterprises",
  "registrationStatus": "Active",
  "principalPlaceOfBusiness": "123, MG Road, Bengaluru, Karnataka, 560001",
  "message": "GSTIN Exists"
}

एक छोटी बारीकी: इस जवाब में GSTIN वाला key बड़े अक्षरों में GSTIN है, जबकि request में छोटे अक्षरों वाला gstin। कोड में इसे ग़लत न पढ़ें।

CIN और निदेशक

अगर आवेदक कंपनी है, तो CIN endpoint से companyName, incorporationDate, cinStatus, companyStatus और directors की सूची मिलती है, जिसमें हर निदेशक का din, name और designation होता है। इससे आप यह देख सकते हैं कि आवेदन पर हस्ताक्षर करने वाला व्यक्ति कंपनी के निदेशकों में दर्ज है या नहीं। यह देखना कि उसे कंपनी की ओर से ऋण लेने का अधिकार है या नहीं, अलग क़ानूनी सवाल है, जिसका जवाब API नहीं देती।

Udyam और PAN से खोज

Udyam endpoint में udyamNumber जाता है और जवाब में found, udyamStatus, enterpriseName, enterpriseType, organizationType और certificateUrl आते हैं। ध्यान दें कि Udyam के जवाब में valid की जगह found है, इसलिए एक सामान्य if (res.valid) वाला कोड यहाँ चुपचाप ग़लत चलेगा। PAN to GSTIN और PAN to Udyam endpoint उन ग्राहकों के काम आते हैं जो सिर्फ़ PAN बताते हैं और GSTIN या Udyam नंबर नहीं जानते: PAN डालिए, और उससे जुड़े GSTIN या Udyam पंजीकरण की सूची पाइए। व्यवसाय की जाँचों का विस्तृत वर्णन GSTIN, CIN और Udyam वाले गाइड में है, और GSTIN पर अलग से GSTIN verification API गाइड में।

Voter ID, Driving Licence और Passport कब इस्तेमाल करें?

हर संस्था के लिए ज़रूरी पहचान-पत्र अलग-अलग होते हैं और वे नीति से तय होते हैं। RBI के KYC direction में "officially valid documents" की परिभाषा है, और उसमें पासपोर्ट, ड्राइविंग लाइसेंस और वोटर पहचान-पत्र जैसे दस्तावेज़ों का ज़िक्र हमने पेज पर देखा। कौन-सा दस्तावेज़ आपकी स्थिति में चलेगा, यह निर्णय compliance का है।

जब नीति में कोई ऐसा दस्तावेज़ माँगा जाए, तब तीनों endpoint काम आते हैं। इनके input अलग हैं, इसलिए ध्यान रखिए:

• Voter ID: voterId और वैकल्पिक name। जवाब में valid, name, dob, gender, age, address और state मिलते हैं।
• Driving Licence: dlNumber और dob दोनों ज़रूरी हैं। जवाब में dlStatus, validUpto और पता वग़ैरह मिलते हैं।
• Passport: fileNumber और dob ज़रूरी हैं, name वैकल्पिक। जवाब का रूप छोटा है: valid, name, dob, applicationType।

ध्यान रहे कि Passport endpoint passport नंबर नहीं, application का file number माँगता है। इसलिए passport नंबर भेजने पर input की जाँच में दिक़्क़त आ सकती है। इन तीनों के जवाब में पता या जन्म-तिथि जैसा निजी डेटा होता है, इसलिए इन्हें लॉग में पूरा मत छापिए। यह बात हम "डेटा की ज़िम्मेदारी" वाले हिस्से में फिर उठाएँगे।

API के जवाब को फ़ैसले में कैसे बदलें?

यह वह जगह है जहाँ ज़्यादातर टीमें ग़लती करती हैं। वे सोचती हैं कि valid: true आया तो आवेदन आगे बढ़ा दो, और valid: false आया तो अस्वीकार। नेहा की टीम ने तीन रास्ते बनाए।

1. आगे बढ़ो (auto-pass): सभी ज़रूरी check सफल और नाम का मिलान आपकी तय सीमा से ऊपर।
2. मानवीय समीक्षा: नाम का आंशिक मिलान, या कोई ऐसा संकेत जो अजीब लगे, या API की अस्थायी विफलता।
3. रोको या अस्वीकार करो: कोई नंबर रिकॉर्ड में है ही नहीं, या स्थिति सक्रिय नहीं है। इसका अंतिम रूप आपकी नीति तय करेगी, और ग्राहक को अस्वीकृति का कारण बताने के नियम भी अलग से देखने होंगे।

// decide.js: सिर्फ़ ढाँचा, थ्रेशोल्ड आपकी risk नीति से आएँगे
export function decidePan(res, { passScore = 90 } = {}) {
  if (!res.valid || res.panStatus !== "VALID") return "REJECT_OR_HOLD";
  const score = Number(res.nameMatchScore); // string में आता है
  if (res.nameMatchResult === "MATCH" && score >= passScore) return "AUTO_PASS";
  return "MANUAL_REVIEW";
}

ऊपर passScore = 90 केवल उदाहरण है, कोई सिफ़ारिश नहीं। अपना थ्रेशोल्ड आप अपने पिछले आवेदनों पर परखकर तय करें। हर निर्णय के साथ referenceId और अपना आंतरिक आवेदन-नंबर साथ-साथ सेव करें, ताकि बाद में कोई पूछे "इस ग्राहक को किस आधार पर आगे बढ़ाया गया था" तो आपके पास जवाब हो।

एक पूरा उदाहरण: तीन check एक साथ जोड़ना

नेहा की टीम ने अपने onboarding सर्वर में एक छोटा orchestrator लिखा, जो तीनों check को सही क्रम में चलाता है और पहली विफलता पर रुक जाता है। इससे दो फ़ायदे हुए: बाद वाले check पर बेकार ख़र्च नहीं हुआ, और हर आवेदन का एक ही "ट्रेल" बना जिसमें हर चरण का referenceId दर्ज रहा।

import { verifyPan } from "./verify-pan.js";
import { decidePan } from "./decide.js";

export async function onboard(app) {
  const trail = [];
  const pan = await verifyPan(app.pan, app.name);
  trail.push({ step: "pan", referenceId: pan.referenceId });
  const d = decidePan(pan);
  if (d !== "AUTO_PASS") return { outcome: d, trail };

  // बैंक खाता disbursal से ठीक पहले अलग सर्विस में जाँचा जाता है
  return { outcome: "AUTO_PASS", trail };
}

यहाँ एक बारीकी है। orchestrator outcome लौटाता है, पर ग्राहक को दिखने वाला संदेश अलग परत से बनता है। इस तरह तकनीकी विफलता का संदेश और "PAN अमान्य" वाला संदेश कभी आपस में नहीं मिलते।

नाकाम आवेदन की एक काल्पनिक कहानी

मान लीजिए एक ग्राहक ने PAN के नाम में पूरा नाम "रवींद्र कुमार शर्मा" भरा, जबकि रिकॉर्ड में "RAVINDRA KUMAR SHARMA" था। नाम का स्कोर थोड़ा कम आया क्योंकि लिपि और वर्तनी का फ़र्क़ था। पुरानी प्रणाली में यह आवेदन अस्वीकार हो जाता, और ग्राहक चला जाता। नई प्रणाली ने उसे मानवीय समीक्षा में डाला, समीक्षक ने दोनों नाम देखे और आगे बढ़ा दिया। ऐसे मामलों का हिसाब रखना नेहा के काम का सबसे उपयोगी मीट्रिक बना: "कितने आवेदन समीक्षा से पार हुए और कितने सचमुच ग़लत निकले।" इसी से तय हुआ कि थ्रेशोल्ड ऊपर या नीचे ले जाना है या नहीं।

ऑपरेशंस टीम की भूमिका कैसे बदलती है

API लगने के बाद ऑपरेशंस टीम हटती नहीं। वह दो जगहों पर काम करती है: समीक्षा की क़तार, और नियमित गुणवत्ता जाँच, जहाँ बेतरतीब चुने गए auto-pass मामलों को वह दोबारा देखती है। यह जाँच इसलिए ज़रूरी है कि स्वचालित प्रणाली की ग़लतियाँ चुपचाप जमा हो सकती हैं। जब किसी नियम में बदलाव हो या API का कोई जवाब बदले, तो इसी जाँच से पता चलता है कि कुछ टूटा है।

"मौजूद नहीं" और "सेवा नहीं चली" में फ़र्क़

valid: false एक पूरा हुआ नतीजा है: सेवा चली और उसने बताया कि नंबर वैध नहीं है। जब सेवा ही न चले (502, 429 या नेटवर्क टाइमआउट), तब आपके पास कोई नतीजा ही नहीं है। इन दोनों को एक ही रास्ते पर मत डालिए। पहली स्थिति में आवेदन आगे नहीं बढ़ेगा, दूसरी स्थिति में आपको दोबारा कोशिश करनी है या मानवीय समीक्षा में भेजना है। ग्राहक को यह नहीं कहना चाहिए कि "आपका PAN अमान्य है" जब असल में हमारी तरफ़ कोई तकनीकी दिक़्क़त थी।

आम ग़लतियाँ और उनके कारण

नीचे वे ग़लतियाँ हैं जो ऐसी integration में बार-बार दिखती हैं। हर एक का कारण और सुधार साथ में है।

नकारात्मक नतीजे पर बार-बार retry

हमारे दस्तावेज़ों के अनुसार valid: false या found: false वाला जवाब भी पूरा और billable verification है। अगर आपका कोड "false आया तो दोबारा कोशिश करो" लिखता है, तो आप उसी ग़लत नंबर पर बार-बार पैसे और call खर्च करेंगे। सुधार: retry केवल उन स्थितियों में करें जहाँ सेवा नहीं चली (नीचे की तालिका देखें)।

referenceId को idempotency key समझ लेना

referenceId हमारी तरफ़ का transaction पहचान-नंबर है। यह idempotency key नहीं है, यानी इसे भेजकर आप दोबारा वही call सुरक्षित नहीं करा सकते। अपने स्तर पर ख़ुद की सुरक्षा बनाइए: एक ही आवेदन पर एक ही PAN के लिए पिछला नतीजा अपने डेटाबेस में रखिए और पहले उसे देखिए, फिर नई call कीजिए।

Input की स्वरूप-जाँच न करना

API input का फ़ॉर्मैट पहले ही जाँच लेती है। ग़लत फ़ॉर्मैट पर 400 और BAD_REQUEST कोड आता है, जैसे "pan must match the format ABCDE1234F"। अगर आप ये जाँच ऐप में पहले ही कर लें (PAN का पैटर्न, IFSC के 11 अक्षर, खाते के 9 से 18 अंक), तो ग्राहक को तुरंत फ़ॉर्म पर ही सही संदेश दिखेगा और एक बेकार call बचेगी।

Production key को client-side में भेज देना

मोबाइल ऐप या ब्राउज़र के कोड में API key डालना सबसे गंभीर ग़लती है। key हमेशा आपके सर्वर पर रहे। ऐप आपके सर्वर से बात करे, और आपका सर्वर StampMitra से।

जवाब के अलग-अलग key-नाम

जैसा हमने ऊपर देखा: PAN में valid, Udyam में found, GSTIN के जवाब में बड़े अक्षर का GSTIN, और बैंक खाते में accountExists। हर endpoint के लिए एक छोटा adapter लिखिए जो इन्हें आपके अपने मानक रूप में बदल दे। वरना एक जगह की सुधार दूसरी जगह टूटेगी।

Errors को कैसे पढ़ें और कब retry करें?

हर त्रुटि इसी रूप में आती है: { "error": { "code", "message", "requestId" } }। requestId को हमेशा अपने लॉग में रखिए। अगर कभी support से बात करनी पड़े ([email protected]), तो यही id हमारे पास आपकी call को पहचानने का सबसे तेज़ रास्ता है।

दस्तावेज़ में 429 का नमूना संदेश है: "Rate limit exceeded: 60 requests per 60 seconds for this endpoint." यानी सीमा प्रति endpoint 60 अनुरोध प्रति 60 सेकंड दिखाई गई है। अपनी असली सीमा के लिए हमेशा docs देखें, क्योंकि वह बदल सकती है। sandbox में एक और कारण से भी 429 आ सकता है: sandbox की आजीवन call quota पूरी होने पर। इसीलिए यह जानना ज़रूरी है कि कौन-सा 429 है, जिसके लिए संदेश पढ़ना होता है।

Backoff का साधारण नियम

502 और 429 पर पहले कुछ सेकंड रुकिए, फिर दोगुना समय, और दो-तीन कोशिशों के बाद छोड़ दीजिए। ग्राहक के सामने स्पिनर अनंत समय तक न घूमे: एक सीमा के बाद आवेदन को "समीक्षा में" दिखाइए और पीछे से बाद में दोबारा चलाइए। त्रुटियों को सँभालने का पूरा ब्योरा API errors और handling गाइड में है।

ग्राहक के डेटा की ज़िम्मेदारी: सहमति, सीमित उपयोग, सीमित अवधि

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

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

ग्राहक को साफ़ भाषा में बताइए कि आप उसका PAN या खाता नंबर किस काम के लिए जाँच रहे हैं। यह जानकारी फ़ॉर्म पर उसी जगह दिखे जहाँ वह नंबर डालता है, किसी लंबी शर्तों वाली स्क्रीन में दबी हुई नहीं। जिस उद्देश्य के लिए डेटा लिया, उसी के लिए इस्तेमाल कीजिए। KYC के लिए लिया गया नंबर विज्ञापन के लिए मत उपयोग कीजिए।

कम से कम डेटा, कम से कम समय

API के जवाब में बहुत-से fields आते हैं, जैसे पिता का नाम और पता। जो आपके निर्णय के लिए ज़रूरी नहीं, उसे सेव ही मत कीजिए। जो सेव करना ज़रूरी है, उसे उतने समय तक रखिए जितना आपकी नीति और लागू नियम कहते हैं। RBI के KYC direction का जो संस्करण हमने पढ़ा, उसमें रिकॉर्ड कम से कम पाँच साल रखने की बात दर्ज थी, लेकिन ताज़ा अवधि आपको अपने compliance विभाग से पक्की करनी होगी। लॉग में पूरा PAN या खाता नंबर कभी मत छापिए। मास्क कीजिए, जैसे ABCDE****F।

StampMitra के साथ डेटा की स्थिति

हमारे नियम और डेटा से जुड़ी शर्तें developer privacy policy, API security policy और data processing addendum में हैं। अगर आप किसी enterprise ग्राहक के लिए यह integration बना रहे हैं, तो ये दस्तावेज़ अपनी legal टीम को दीजिए।

Sandbox में कैसे परखें, और क्या परखें?

Sandbox में आपकी call असली पैसे से नहीं कटती: environment सर्वर पर key से तय होता है, और sandbox call रिकॉर्ड होती है पर आपका wallet नहीं घटाती। लेकिन sandbox की एक आजीवन call quota है, जिसके बाद 429 मिलता है। इसलिए sandbox की calls को सोच-समझकर खर्च कीजिए।

Sandbox में जाँचने की सूची

• हर endpoint का सफल नमूना जवाब आपके adapter से सही रूप में निकलता है।
• ग़लत फ़ॉर्मैट पर 400 मिलता है और आपका फ़ॉर्म उसे ग्राहक की भाषा में दिखाता है।
• बिना scope वाली key पर 403 मिलता है और आपका कोड उसे "retry" की जगह "विन्यास की ग़लती" की तरह लॉग करता है।
• 429 पर backoff चलता है।
• referenceId आपके डेटाबेस में आवेदन से जुड़कर सेव हो रहा है।
• नाम का आंशिक मिलान मानवीय समीक्षा की क़तार में जा रहा है, अस्वीकार नहीं हो रहा।

नेहा की टीम का एक नियम

उन्होंने sandbox की कुछ call केवल "ग़लत इनपुट" और "ग़लत key" जैसी नकारात्मक स्थितियों के लिए बचाकर रखीं, क्योंकि सफल रास्ता तो सभी जाँच लेते हैं। उत्पादन में असली दर्द नकारात्मक रास्तों से आता है। sandbox और production के फ़र्क़ पर अलग से sandbox बनाम production API key गाइड देखिए।

Production में जाने से पहले क्या देखें?

Production access अपने-आप नहीं खुलता। उसके लिए आपके अकाउंट का सत्यापन और हर उत्पाद की entitlement चाहिए, और इसकी शर्तें developer onboarding verification policy में दी गई हैं। इसके बाद launch से पहले यह सूची देखिए:

1. sk_live_... key केवल आपके सर्वर के secrets में है, कहीं और नहीं।
2. जिन scopes पर IP allowlist लगती है (जैसे PAN और RC), उनके लिए आपके production सर्वर का IP सूची में जुड़ चुका है।
3. wallet में पर्याप्त बैलेंस है और बैलेंस घटने पर सूचना देने वाली व्यवस्था है, ताकि 402 ग्राहकों के सामने पहली बार न दिखे।
4. 402, 429 और 502 पर आपका व्यवहार तय और परखा हुआ है।
5. लॉग में निजी डेटा मास्क होता है, और requestId तथा referenceId सेव होते हैं।
6. compliance टीम ने नतीजों को आपके KYC नीति-दस्तावेज़ से जोड़कर देख लिया है, यानी किस check का नतीजा किस नीति-चरण को पूरा करता है, यह लिखा हुआ है।
7. launch के पहले हफ़्ते के लिए निगरानी: कितने आवेदन auto-pass, कितने मानवीय समीक्षा, कितने रुके।

धीरे-धीरे शुरू कीजिए

पहले दिन सारा ट्रैफ़िक नई प्रणाली पर मत डालिए। पहले कुछ प्रतिशत आवेदन API से चलाइए और बाक़ी को पुरानी प्रक्रिया पर रहने दीजिए। दोनों के नतीजे साथ-साथ देखिए। जब भरोसा बन जाए तब बढ़ाइए। "कितने प्रतिशत" यह आपकी टीम तय करेगी।

लागत का हिसाब कैसे लगाएँ

हर सफल call पर शुल्क लगता है, और नकारात्मक नतीजा भी सफल call गिना जाता है। इसलिए प्रति स्वीकृत लोन की लागत निकालते समय सिर्फ़ पास हुए आवेदन नहीं, सभी आवेदन गिनिए। एक सरल सूत्र: (प्रति आवेदन check की संख्या x प्रति call दाम x कुल आवेदन) / स्वीकृत लोन। दाम pricing पेज से लीजिए। क्रम सही रखने से यह लागत घटती है, क्योंकि जो आवेदन पहले check पर ही रुक गया उस पर आगे के check का ख़र्च नहीं होता।

launch के बाद पहले तीस दिन की निगरानी

Production में जाने के बाद पहले महीने में नेहा की टीम हर हफ़्ते चार चीज़ें देखती है। पहली, हर endpoint पर सफल और विफल call का अनुपात, ताकि 400 की अचानक बढ़ोतरी से पता चले कि फ़ॉर्म की जाँच कहीं टूटी है। दूसरी, 402 की संख्या: अगर यह एक बार भी दिखे तो मतलब wallet की सूचना-व्यवस्था में कमी है। तीसरी, मानवीय समीक्षा की क़तार की लंबाई और औसत इंतज़ार, क्योंकि लंबी क़तार का मतलब वही पुराना drop-off लौट आना है। चौथी, auto-pass किए गए मामलों में से बाद में ग़लत निकले आवेदन, जो आपके थ्रेशोल्ड की असली परीक्षा हैं।

इन चारों के लिए अलग से कोई जटिल dashboard ज़रूरी नहीं। अपने लॉग में requestId, referenceId, endpoint का नाम, HTTP स्थिति और फ़ैसला (auto-pass, समीक्षा, रोका) दर्ज कीजिए। इन्हीं पाँच कॉलम से ऊपर के सारे सवालों के जवाब निकल आते हैं। निजी डेटा इन कॉलमों में नहीं जाना चाहिए।

टीम में किसकी क्या ज़िम्मेदारी हो

एक साफ़ बँटवारा बहुत झंझट बचाता है। डेवलपर टीम integration, key, scope और त्रुटि-प्रबंधन सँभालती है। प्रोडक्ट टीम का काम है कि फ़ंनल के किस चरण पर कौन-सा check लगे और ग्राहक को क्या संदेश दिखे। compliance टीम तय करती है कि कौन-सा नतीजा किस नीति-चरण को पूरा माना जाएगा, और थ्रेशोल्ड के बदलाव पर अंतिम मंज़ूरी देती है। ऑपरेशंस टीम समीक्षा की क़तार चलाती है। जब कोई ग़लती हो तो यह बँटवारा बताता है कि पहला फ़ोन किसे जाए। StampMitra की तरफ़ से किसी तकनीकी सवाल के लिए [email protected] ही एकमात्र पता है।

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

हर काम API से करना ठीक नहीं। यह निर्णय-गाइड एक शुरुआती नज़रिया देता है।

तीन सवाल जो हर बार काम आते हैं

पहला: क्या यह "रिकॉर्ड में नंबर का मिलान" वाला सवाल है? तो API सही है। दूसरा: क्या इस सवाल का जवाब किसी इंसान या संस्था की पहचान या मंशा पर टिका है? तो API सिर्फ़ संकेत देगी, निर्णय आपका है। तीसरा: क्या कोई नियम बताएगा कि यह काफ़ी है? तो नियम की व्याख्या अपने सलाहकार से पूछिए।

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

StampMitra एक निजी LegalTech प्लेटफ़ॉर्म है, जिसे Bani Global Industries LLP (LLPIN ACI-6373) चलाती है। हम सरकारी एजेंसी नहीं हैं और कानूनी सलाह नहीं देते। हमारा काम इतना है कि आपके डेवलपर को verification का एक साफ़, एक-सा रूप वाला REST इंटरफ़ेस मिले।

आज की तारीख़ में StampMitra के साथ आप ये कर सकते हैं:

• ग्यारह verification endpoint से PAN, GSTIN, Vehicle RC, Voter ID, Driving Licence, Passport, CIN, Udyam, PAN to GSTIN, PAN to Udyam और Bank Account की जाँच।
• हर सफल call पर एक referenceId, जिसे आप अपने audit रिकॉर्ड से जोड़ सकते हैं।
• हर त्रुटि एक ही रूप में: code, message और requestId।
• scope वाली key, sandbox और production का अलग-अलग environment, और संवेदनशील scopes के लिए IP allowlist।
• sandbox में मुफ़्त परीक्षण, ताकि आप पैसे लगाए बिना integration परख सकें। एक call का दाम, उदाहरण के लिए PAN का ₹5 और बैंक खाते का ₹4, pricing पेज की ताज़ा दरों से आता है।
• MCP, SDKs और Postman collection जैसे औज़ार, जिनसे शुरुआती परीक्षण तेज़ होता है।

हमारी सीमाएँ भी साफ़ हैं। StampMitra की verification सूची में आज Aadhaar आधारित eKYC, चेहरे का मिलान, liveness, वीडियो KYC, CKYC रजिस्ट्री से जुड़ाव या AML screening नहीं है। ये अलग प्रणालियाँ हैं और आपको इनके लिए अपनी व्यवस्था या दूसरे प्रदाता रखने पड़ सकते हैं। verification के payment webhooks और ऑर्डर-आधारित webhooks का पेज "Coming soon" दिखाता है, इसलिए verification के नतीजों के लिए आपको उसी call के जवाब पर निर्भर रहना है, जो synchronous रूप में आता है।

आगे क्या सोचा जा रहा है

आगे की योजनाएँ हैं, वादे नहीं। हमारी योजना है कि webhooks का पेज "Coming soon" से आगे बढ़े और डेवलपर अनुभव बेहतर हो। कोई विशेष सुविधा चाहिए तो contact पेज या [email protected] पर लिखिए। हम किसी तारीख़ का वादा नहीं करते, इसलिए अपनी योजना आज की सुविधाओं पर बनाइए।

शुरू करने का सबसे छोटा रास्ता: signup करें, sandbox key लें, ऊपर वाला PAN का cURL चलाएँ, और अपने compliance विभाग को पहला referenceId दिखाकर बात शुरू करें।

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"
}

{
  "referenceId": "SMV-20260927-3B71A0",
  "valid": true,
  "nameAtBank": "RAVI KUMAR",
  "bankName": "ICICI Bank",
  "utr": "017952100012345",
  "city": "Mumbai",
  "branch": "Andheri West",
  "micr": "400229002",
  "nameMatchScore": "100",
  "nameMatchResult": "GOOD_MATCH",
  "accountStatus": "ACCOUNT_IS_VALID",
  "accountStatusCode": "1",
  "ifscDetails": {
    "bank": "ICICI Bank",
    "ifsc": "ICIC0001234",
    "micr": "400229002",
    "address": "Andheri West, Mumbai",
    "city": "Mumbai",
    "state": "Maharashtra",
    "branch": "Andheri West"
  }
}

{
  "referenceId": "SMV-20260927-3D71Q9",
  "regNo": "MH12AB1234",
  "registrationStatus": "VALID",
  "ownerName": "RAHUL KUMAR",
  "ownerFatherName": "SURESH KUMAR",
  "vehicleClass": "LMV",
  "vehicleManufacturerName": "MARUTI SUZUKI",
  "model": "SWIFT",
  "vehicleColor": "WHITE",
  "chassis": "MA3ERLF1S00123456",
  "engine": "K12MN1234567",
  "registrationDate": "2019-05-14",
  "rcStatus": "ACTIVE",
  "rcExpiryDate": "2034-05-13",
  "insuranceUpto": "2025-05-13",
  "isCommercial": false
}

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